Vite SSR BOOST

Super easy framework based on Vite for create awesome SSR or SPA applications on React and React Router.

Key features:

• Develop ⚡charged⚡ server side applications with React streaming 💨 support.
• Unlocks Suspense for server side applications.
• Switch between SPA and SSR in 1 second.
• Charged CLI out of box.
• Deploy to AWS Amplify/Docker in SPA/SSR mode for 5 sec.
• Very easy to migrate, very easy to use.
• All the power of vite⚡
• All the power of react-router🛣
• Easy-peasy develop for Capacitor

Table of contents

• Getting started
• How to use
• Example
• Plugin options
• Useful imports
• CLI
• Warning
• Use Cases
• Bugs and feature requests
• License

Getting started

The package is distributed using npm, the node package manager.

npm i --save @lomray/vite-ssr-boost

How to use

Explore template to more understand how it works or:

1. Add plugin to vite config:

1/**
2 * vite.config.ts
3 */
4
5import { defineConfig } from 'vite'
6import react from '@vitejs/plugin-react'
7/**
8 * Import plugin
9 */
10import SsrBoost from '@lomray/vite-ssr-boost/plugin';
11
12// https://vitejs.dev/config/
13export default defineConfig({
14  /**
15   * Change root not necessary, but more understandable
16   */
17  root: 'src',
18  publicDir: '../public',
19  build: {
20    outDir: '../build',
21  },
22  /**
23   * Put here
24   */
25  plugins: [SsrBoost(), react()],
26});
27

2. Create client entrypoint:

1/**
2 * src/client.tsx
3 */
4import entryClient from '@lomray/vite-ssr-boost/browser/entry';
5import App from './App.tsx'
6import routes from './routes';
7
8void entryClient(App, routes, {
9  /**
10   * (optional). Client configuration 
11   */
12  init: () => {},
13  /**
14   * (optional). Configure router options
15   * @see createBrowserRouter second arg
16   */
17  routerOptions: {},
18  /**
19   * (optional). Customization create router function, e.g. use from sentry one
20   */
21  createRouter: createBrowserRouter,
22  /**
23   * (optional). Change root id
24   */
25  rootId: 'root',
26});

3. Create server entrypoint:

1/**
2 * src/server.ts
3 */
4import entryServer from '@lomray/vite-ssr-boost/node/entry';
5import App from './App';
6import routes from './routes';
7
8export default entryServer(App, routes, {
9  /**
10   * Request timeout (If your backend is slow, increase this value)
11   */
12  abortDelay: 15000, // default: 15000 (ms)
13  /**
14   * Server configuration (optional)
15   */
16  init: () => ({
17    /**
18     * (optional). Called once after express server creation.
19     * E.g. use for configure express middlewares
20     */
21    onServerCreated: () => {},
22    /**
23     * (optional). Called once after express server started.
24     */
25    onServerStarted: () => {},
26    /**
27     * (optional). Called on each incoming request.
28     * E.g. configure request state, create state manager etc.
29     */
30    onRequest: async () => {},
31    /**
32     * (optional). Called when react router and it's context was created.
33     * E.g. here you can switch stream depends on req.headers, for search crawlers you can disable stream.
34     */
35    onRouterReady: () => {},
36    /**
37     * (optional). Called when application shell is ready to send on client.
38     * E.g. here you can modify header or footer.
39     */
40    onShellReady: () => {},
41    /**
42     * (optional). Called when application shell or suspense resolved and sent to the client.
43     * E.g. here you can add some payload like custom state (any manager state) to response. 
44     */
45    onResponse: () => {},
46    /**
47     * (optional). Stream error callback. Catch stream errors.
48     */
49    onError: () => {},
50    /**
51     * (optional). Called when application shell or all html (depends on stream option) is ready to send on client.
52     * E.g. here you can send any context or state to client.
53     */
54    getState: () => {},
55  }),
56  /**
57   * (optional). Customize production log handler
58   * @see @lomray/vite-ssr-boost/services/logger
59   */
60  loggerProd: new Logger(),
61  /**
62   * (optional). Customize development log handler
63   * @see @lomray/vite-ssr-boost/services/logger
64   */
65  loggerDev: new Logger(),
66  /**
67   * (optional). Configure pre-builded middlewares
68   */
69  middlewares: {
70    /**
71     * @see CompressionOptions from 'compression' package
72     */
73    compression: {},
74    /**
75     * @see ServeStaticOptions from 'serve-static' package
76     */
77    expressStatic: {},
78  },
79  /**
80   * (optional). Configure router static handler options
81   * @see createStaticHandler second arg
82   */
83  routerOptions: {},
84});

4. Replace package.json scripts:

1{
2  ...
3  "scripts": {
4    "develop": "ssr-boost dev",
5    "build": "ssr-boost build",
6    "start:ssr": "ssr-boost start",
7    "start:spa": "ssr-boost start --only-client",
8    "preview": "ssr-boost preview"
9  },
10  ...
11}

5. Let's do the magic:

1npm run develop

Plugin options

1import SsrBoost from '@lomray/vite-ssr-boost/plugin';
2import type { FCRoute } from '@lomray/vite-ssr-boost/interfaces/fc-route';
3
4/**
5 * Configuration
6 */
7SsrBoost({
8  /**
9   * index.html file path
10   */
11  indexFile: 'index.html', // default: index.html
12  /**
13   * Server entrypoint file
14   */
15  serverFile: 'server.ts', // default: server.ts
16  /**
17   * Client entrypoint file
18   */
19  clientFile: 'client.ts', // default: client.ts
20  /**
21   * Add tsconfig aliases to vite config aliases
22   */
23  tsconfigAliases: true, // default: true
24  /**
25   * Path contains routes declaration files (need to detect route files).
26   */
27  routesPath: undefined, //default: undefined
28  /**
29   * Create additional SPA entrypoint: index-spa.html
30   * Can be used for service worker: createHandlerBoundToURL("index-spa.html")
31   */
32  spaIndex: false, // default: false
33  /**
34   * Additional entry points for build
35   */
36  entrypoint: [], // default: undefined
37})

Useful imports

1/**
2 * Components
3 */
4// Navigate component based on react-router-dom with server-side support
5import Navigate from '@lomray/vite-ssr-boost/components/navigate';
6// Change server response status
7import ResponseStatus from '@lomray/vite-ssr-boost/components/response-status';
8// Scroll page to top after navigate
9import ScrollToTop from '@lomray/vite-ssr-boost/components/scroll-to-top';
10// HOC for wrap component in Suspense
11import withSuspense from '@lomray/vite-ssr-boost/components/with-suspense';
12// Only client side components
13import OnlyClient from '@lomray/vite-ssr-boost/components/only-client';
14
15/**
16 * Helpers
17 */
18// Get server state (e.g. state manager) on client side
19import getServerState from '@lomray/vite-ssr-boost/helpers/get-server-state';
20
21/**
22 * Interfaces
23 */
24// interfaces for route components
25import type { FCRoute, FCCRoute } from '@lomray/vite-ssr-boost/interfaces/fc-route';
26// interface for define routes
27import type { TRouteObject } from '@lomray/vite-ssr-boost/interfaces/route-object';

Client side components import example:

1<OnlyClient load={() => import('external-package')}>
2  {(LoadedComponent) => (
3    <LoadedComponent />
4  )}
5</OnlyClient>

CLI

Explore all commands and options:

1ssr-boost -h

WARNING

Route imports of the following types are supported:

1import { RouteObject } from 'react-router-dom';
2import HomePage from './pages/home'; // not lazy imports should be directly in file where it use
3
4const importPath = './pages/home';
5
6const routes: RouteObject[] = [
7  {
8    path: '/home',
9    Component: HomePage, // support
10    element: <AppLayout />, // support
11    lazy: () => import('./pages/home'), // support
12    lazy: () => import(importPath), // not support, but you can move logic in separate file and import it with supported case
13  }
14];

Use Cases

Change basename

1/**
2 * Configure client
3 */
4void entryClient(App, routes, {
5  routerOptions: {
6    basename: '/custom',
7  },
8});

1/**
2 * Configure server
3 */
4export default entryServer(App, routes, {
5  routerOptions: {
6    basename: '/custom',
7  },
8});

Change base for static assets

1// https://vitejs.dev/config/
2export default defineConfig({
3  base: '/static',
4});

1/**
2 * Configure server
3 * NOTE: 'basename' should be equal to 'base' from vite config 
4 */
5export default entryServer(App, routes, {
6  middlewares: {
7    expressStatic: {
8      basename: '/static',
9    },
10  },
11});

Capacitor additional endpoint

1// https://vitejs.dev/config/
2export default defineConfig({
3  plugins: [
4    SsrBoost({
5      entrypoint: [
6        {
7          name: 'mobile',
8          type: 'spa',
9          clientFile: './src/mobile.tsx',
10          buildOptions: '--mode mobile',
11        },
12      ],
13    }),
14    react(),
15  ],
16});

1const AppMobile: FC = (props) => {
2  // some mobile logic
3
4  return <App {...props} />;
5}
6
7/**
8 * src/mobile.tsx
9 */
10void entryClient(AppMobile, routes, {});

Bugs and feature requests

Bug or a feature request, please open a new issue.

License

Made with 💚

Published under MIT License.