Configuration

A VitNode app has two configuration files, and the line between them is one question: may a browser hold this?

vitnode.config.ts - the shared config

import { blogPlugin } from '@vitnode/blog/config'
import { buildConfig } from '@vitnode/core/vitnode.config'

export const vitNodeConfig = buildConfig({
  debug: false,
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      { code: 'pl', name: 'Polski' },
    ],
    timeZone: 'UTC',
  },
  metadata: {
    shortTitle: 'VitNode',
    title: 'VitNode',
  },
  plugins: [blogPlugin()],
  theme: {
    defaultTheme: 'system',
  },
})

Three very different readers depend on this file:

1. The document shell renders metadata, theme and debug - in the browser as well as on the server.
2. The locale runtime derives routing from i18n.
3. Your Vite build loads it with jiti while Vite is still resolving its own config, to find out which plugins to generate route, navigation and content-registry imports for.

buildConfig keeps locales a tuple of literal types, so a Locale derived from it is 'en' | 'pl' rather than string, and defaultLocale is checked against the list right beside it:

export type Locale = (typeof vitNodeConfig.i18n.locales)[number]['code']

Enabled plugins

Register a plugin with its own factory:

import { blogPlugin } from '@vitnode/blog/config'

plugins: [blogPlugin()]

The factory carries the plugin's identity, its locale barrel and its route declarations - plain data, and nothing that renders. Its AdminCP navigation and its Content Engine screens live in the plugin's admin/nav and admin/content modules instead, and they never pass through this object.

What a TanStack Start app renders comes back through generated projections of those modules, and that is the part worth knowing:

One literal import per configured plugin, written at build time. So a content type's editing screen - a Tiptap field, a form layout, a table cell - arrives with the route that renders it, not with the config that the document shell imports. Spreading admin/content into the factory undoes exactly that: the whole editing stack rides along with every public page. See Plugin routes and Plugin frontend modules.

vitnode.server.config.ts - the server-only companion

Message loaders read JSON out of a package's build output, which is exactly what the shared config cannot carry. They go here instead:

import '@tanstack/react-start/server-only'
import { buildServerConfig } from '@vitnode/core/vitnode.config'

import { appMessages } from '#/locales/app'
import { packageMessages } from '#/locales/packages'
import { vitNodeConfig } from '#/vitnode.config'

export const vitNodeServerConfig = buildServerConfig({
  config: vitNodeConfig,
  messages: appMessages,
  packageMessages,
})

It holds the shared config rather than repeating any of it, so the locale list your message loaders are resolved against is the same object the router and the document shell read. Hand the whole thing to the loader:

export const loadIntlMessages = createIntlMessagesLoader(vitNodeServerConfig)

packageMessages is one line per language a package ships, and messages is where you reword a string a package translates differently to how you want it. Languages & Localization covers both.

start.ts - the request pipeline

TanStack Start expects a src/start.ts. In a VitNode app it is one call:

import { createVitNodeStart } from '@vitnode/core/tanstack/start'

import { vitNodeConfig } from '#/vitnode.config'

export const startInstance = createVitNodeStart({ config: vitNodeConfig })

createVitNodeStart installs three things, and none of them is optional:

Why documents are never shared-cacheable

Every page VitNode renders streams a dehydrated TanStack Query cache into its HTML, and that cache always holds the visitor's own session - inside /admin, an administrator's entire permission set. So the directive is forced, not defaulted: a route that sets public, max-age=60 is overwritten rather than obeyed, because the route is not in a position to know what is in the body it would be publishing.

Only text/html responses are touched. Everything else keeps what it had.

Adding your own middleware

For things your installation genuinely owns - a request id, a tracing span, a maintenance-mode gate:

import { createMiddleware } from '@tanstack/react-start'
import { createVitNodeStart } from '@vitnode/core/tanstack/start'

import { vitNodeConfig } from '#/vitnode.config'

const requestId = createMiddleware().server(async ({ next }) => {
  const result = await next()
  result.response.headers.set('x-request-id', crypto.randomUUID())

  return result
})

export const startInstance = createVitNodeStart({
  config: vitNodeConfig,
  requestMiddleware: [requestId],
})

Ordering is guaranteed: CSRF first, then locale handling, then your list in the order you declared it. You cannot get in front of either. That is not tidiness - a locale redirect ends the request, so middleware running before it would run twice for every visitor who arrives at a non-canonical URL, once for the redirect and once for the page.

vite.config.ts

One VitNode plugin, which is the environment handling, the dev server's dependency pre-bundling, the SSR externals and the plugin route generator in the order they have to run:

import { vitnode } from '@vitnode/core/framework/vite'

export default defineConfig({
  plugins: [
    vitnode({ appRoot: import.meta.dirname }),
    nitro({ compressPublicAssets: { brotli: true, gzip: true } }),
    tailwindcss(),
    tanstackStart(),
    viteReact(),
  ],
})

compressPublicAssets writes a .br and a .gz twin next to every built asset, so the Node server from pnpm start serves scripts and styles compressed the way a CDN would. The server-rendered HTML itself is not compressed by the Node server; put a reverse proxy or a platform such as Vercel in front of it for that.

appRoot has to be import.meta.dirname: a Vite config is loaded with the working directory set to wherever the command ran, which in a monorepo is regularly the repository root.

Publish an extra NEXT_PUBLIC_* key to the browser with clientEnv:

vitnode({ appRoot: import.meta.dirname, clientEnv: ['NEXT_PUBLIC_MAP_KEY'] })

Everything named there is compiled into JavaScript anyone can read, so add a key only when something in the browser genuinely reads it. The four plugins are still exported individually - vitNodeEnv, vitNodeOptimizeDeps, vitNodeSsrExternals, vitNodePluginRoutes - if you ever need to drop or reorder one.

What gets externalised from the server render

You do not write an ssr.external list, because the right answer changes between the two commands:

Externalising in dev is the tempting mistake, and it fails quietly: an external module is imported by Node, whose module cache lives as long as the process. The browser hot-reloads your edit, the server render keeps the copy it loaded at startup, and React reports a hydration mismatch on markup you already fixed. Only a restart clears it - which is exactly the loop this plugin removes.

The build list is @vitnode/core, every plugin in your vitnode.config.ts and tslib. It comes from the same configured plugin list the route generator reads, so removing a plugin from your config is one edit, not two.

Learn More