⚠
vite-plugin-ssr has been renamed Vike, see migration guide.

Header file (.h.js)

+config.h.js files are part of the V1 design.

Transformation

Vite-plugin-ssr transforms .h.js files, such as this:

// /pages/some-page/+config.h.js

import Page from './some-file'
import onBeforeRender from './some-other-file'

export default {
  Page,
  onBeforeRender
}

Into:

// /pages/some-page/+config.h.js

const Page = 'import:./some-file';
const onBeforeRender = 'import:./some-other-file';

export default {
  Page,
  onBeforeRender
}

.h.js files are only meant for config files (i.e. any .h.js file should be a +config.h.js file).

Why

Instead of +config.h.js we can define +config.js:

// /pages/some-page/+config.js

export default {
  Page: 'import:./some-file',
  onBeforeRender: 'import:./some-other-file'
}

But then we lose IntelliSense such as auto-import, refactoring, type safety, and go-to-definition. That's why we recommend to define +config.h.js instead of +config.js.

Real imports cannot be used. Consider this example:

// +config.h.js

// onRenderClient() should be loaded only on the client-side
import onRenderClient from './some-file'
// onRenderHtml() should be loaded only on the server-side
import onRenderHtml from './some-other-file'

export default { onRenderHtml, onRenderClient }

Using 'import:./some-file' instead of a real import import onRenderClient from './some-file' enables vite-plugin-ssr to load the onRenderClient() hook only when needed and in the right environment.

Optional

As mentioned in the previous section, .h.js files are optional.

Instead of defining a +config.h.ts file:

// /pages/some-page/+config.h.ts

import type { Config } from 'vite-plugin-ssr/types'
import Page from './some-file'
import { onBeforeRender } from './some-other-file'

export default {
  Page,
  onBeforeRender
} satisfies Config

We can define a +config.ts file (without .h):

// /pages/some-page/+config.ts

import type { Config } from 'vite-plugin-ssr/types'

export default {
  Page: 'import:./some-file',
  onBeforeRender: 'import:./some-other-file:onBeforeRender'
} satisfies Config

Inline hooks code

Following is forbidden:

// /pages/some-page/+config.h.js

export default {
  Page() {
    // ...
  },
  onBeforeRender() {
    // ...
  }
}

Vite-plugin-ssr throws:

[Wrong Usage] The code of config 'Page' cannot live inside /pages/some-page/+config.h.js

Do this instead:

// /pages/some-page/+config.h.js

import Page from './some-file'
import onBeforeRender from './some-other-file'

export default { Page, onBeforeRender }

Not re-exported imports

If an import isn't re-exported by export default { ... }, then it won't be included in any runtime.

// +config.h.js

// These two imports aren't included in any runtime.
import { something } from './some-file'
// This import has no effect. (CSS should be imported in runtime code such as +Page.js instead.)
import './some.css'

// This log is printed only when vite-plugin-ssr reads +config.h.js files. It
// isn't included in the client nor the server runtime.
console.log(something) // Prints: 'import:./some-file:something'

export default {
  // `something` isn't re-exported here
}