Configuration

Gemkit is an Rsbuild plugin. Add it to rsbuild.config.ts:

import { defineConfig } from '@rsbuild/core';
import { pluginGemkit } from '@mantou/gemkit/plugin';

export default defineConfig({
  plugins: [
    pluginGemkit({
      title: 'My Site',
      titleTemplate: '%s | My Site',
    }),
  ],
});

Plugin options

title

• Type: string
• Default: ''

The site title. It is used for pages without a title option.

titleTemplate

• Type: string
• Default: '%s'

The title template. The first %s is replaced with the page title. A page title is ignored when the template has no %s.

srcDir

• Type: string
• Default: 'src'

The directory that contains pages, locales, elements, app.ts, app.server.ts and index.html. It is resolved from the project root and can point to another package that provides the pages. .gemkit and dist are still generated in the project root.

defaultLanguage

• Type: string
• Default: 'en' when en.json exists, otherwise the first language file by name

The default language. It has no URL prefix unless prefixDefaultLanguage is enabled. It must have a language file.

prefixDefaultLanguage

• Type: boolean
• Default: false

Put the default language under a prefix too, for example /en/about. Unprefixed paths redirect to the default language, including on a static host.

prerender

• Type: boolean
• Default: true

Prerender static routes and the dynamic routes returned by paths at build time. When false, every page is rendered on demand and needs a server.

Individual pages and layouts can opt out in their server module with export const prerender = false, or in a layout to disable it for all of its pages.

gem

• Type: UnpluginGemOptions
• Default: undefined

Options passed to unplugin-gem. Gemkit sets the include paths, auto-import of Gem APIs, common @mantou/gemkit APIs (except HttpError, formatTitle and types), i18n, apis and <srcDir>/elements elements, style and HTML minification, selector compatibility, preload and SSR, and enables HMR in development. Options here override those defaults; hmr can still be overridden separately.

autoImport is merged with the Gemkit defaults instead. Keys are package names or aliases, not file paths. src is an alias of <srcDir> (in both the bundler and .gemkit/tsconfig.json), and by default <app-foo> imports src/elements/foo. Setting elements.src replaces that default:

pluginGemkit({
  gem: {
    autoImport: {
      members: { 'src/utils': ['format'] },
      elements: {
        src: { 'app-*': '/components/*' },
        'my-ui': { 'my-*': '/elements/*' },
      },
    },
  },
});

Generated files

Gemkit generates into .gemkit:

.gemkit is ignored by Git. Extend its tsconfig to get types for $gemkit/* and auto-imports:

{
  "extends": "./.gemkit/tsconfig.json"
}

The generated files are overwritten at every build. Don't import them directly, except $gemkit/i18n and $gemkit/api.

Build output

The HTML template is moved out of dist/web after the client build, so a static host doesn't serve it as the home page. See Deploy.

Environment

Renderer

@mantou/gemkit/server exports createRenderer(options). It creates the renderer used by the build and by gemkit start, with the app, server modules, endpoints, i18n and title options. It is an advanced API for integrations that provide their own server; normal applications use gemkit start.