Gracile/Vite configuration

API references extracted from the Gracile code base.
Examples, functions, classes, constants, type declarations…

Interface: GracileConfig

Defined in: packages/engine/dist/user-config.d.ts:72

Example

/vite.config.js

import { gracile } from '@gracile/gracile/plugin';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		gracile({
			output: 'server',

			dev: {
				locals: (_context) => {
					return {
						requestId: crypto.randomUUID(),
						userEmail: 'admin@admin.home.arpa',
					};
				},
			},

			routes: {
				exclude: ['**/a-defective-route.ts'],
			},
		}),
	],
});

Properties

Property Type Default value Description Defined in

dev?

object

undefined

Settings for the development mode.

packages/engine/dist/user-config.d.ts:125

dev.locals?

(context) => unknown

undefined

Get incoming request context and apply locals for the Gracile request handler. Useful for mocking the production server.

For server mode only.

Not needed when using server.entry — the user’s own middleware provides locals directly.

packages/engine/dist/user-config.d.ts:135

experimental?

object

undefined

Future, unstable features flags.

packages/engine/dist/user-config.d.ts:242

experimental.generateRoutesTypings?

boolean

undefined

Experimental

Automatically typed route paths.

packages/engine/dist/user-config.d.ts:247

litSsr?

object

undefined

‐

packages/engine/dist/user-config.d.ts:205

litSsr.renderInfo?

Partial<RenderInfo>

undefined

Lets you extend Gracile’s SSR pipeline with custom Lit SSR ElementRenderer subclasses. This is the foundation for features like Islands, which register a renderer for the <is-land> custom element to server-render components from other UI frameworks.

In most cases, you do not set this option manually — add-on plugins (like gracileIslands()) register their renderers automatically via the plugin context communication channel. However, you can use it directly for advanced use cases:

import { gracile } from '@gracile/gracile/plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    gracile({
      litSsr: {
        renderInfo: {
          elementRenderers: [
            // Your custom ElementRenderer subclass
          ],
        },
      },
    }),
  ],
});

packages/engine/dist/user-config.d.ts:237

output?

"static" | "server"

 
'static'

The target output for the build phase.

See the documentation.

packages/engine/dist/user-config.d.ts:80

pages?

object

undefined

Settings for pages in /src/routes.

packages/engine/dist/user-config.d.ts:175

pages.premises?

object

undefined

Premises are the document and the properties necessary for page template rendering.

You can access them via:

  • .../_my-route/__index.props.json
  • .../_my-route/__index.doc.html

They are accessible with the dev/server handler and are outputted as static files for the static output or for server pre-rendered pages.

They can be use for implementing client-side routing.

packages/engine/dist/user-config.d.ts:190

pages.premises.exclude?

string[]

undefined

Exclude routes with a glob filter array.

packages/engine/dist/user-config.d.ts:202

pages.premises.expose?

boolean

 
false

‐

packages/engine/dist/user-config.d.ts:194

pages.premises.include?

string[]

undefined

Include routes with a glob filter array.

packages/engine/dist/user-config.d.ts:198

routes?

object

undefined

Settings for routes in /src/routes.

packages/engine/dist/user-config.d.ts:142

routes.define?

() => MaybePromise<ProgrammaticRoute[]>

undefined

Define programmatic routes alongside file-based routes.

The returned route definitions are merged with the file-based routes found in src/routes/. If a programmatic route’s pattern conflicts with a file-based route, the programmatic route takes priority.

The async function signature allows fetching route definitions from a CMS, reading an OpenAPI spec, or any other async source.

Example

gracile({
  routes: {
    define: async () => [
      { pattern: '/api/posts', filePath: 'src/api/posts.ts' },
      { pattern: '/blog/:slug', filePath: 'src/blog/post.ts' },
      { pattern: '/docs/:path*', filePath: 'src/docs/catchall.ts' },
    ],
  },
});

packages/engine/dist/user-config.d.ts:170

routes.exclude?

string[]

undefined

Exclude routes with an array of patterns. Useful for debugging.

packages/engine/dist/user-config.d.ts:146

server?

object

undefined

Settings for server mode.

Only meaningful when output is 'server'.

packages/engine/dist/user-config.d.ts:99

server.entry?

string

undefined

Path to the user’s server entry file (e.g. './server.ts').

When set, Gracile will:

  • Dev: load the file via the Vite SSR environment and bridge it into the dev server as middleware (Vite keeps the HTTP listener).
  • Build: use it as the SSR build input so the entire server is bundled into dist/server/.

The entry file should import { handler } from 'gracile:handler' and export a default app (Hono/Express) instance.

Example

gracile({
  output: 'server',
  server: { entry: './server.ts' },
})

packages/engine/dist/user-config.d.ts:120

trailingSlash?

"always" | "never" | "ignore"

 
'ignore'

Controls how trailing slashes are matched on incoming URLs.

  • 'ignore' — Match regardless of whether a trailing / is present. /about and /about/ both resolve to the same route. (default)
  • 'always' — Only match URLs that include a trailing slash (e.g. /about/). Requests without one are redirected: 301 for GET, 308 for other methods.
  • 'never' — Only match URLs that do not include a trailing slash (e.g. /about). Requests with one are redirected: 301 for GET, 308 for other methods.

packages/engine/dist/user-config.d.ts:93