Configuration

systhema.config.ts is the one place a project configures Systhema: which tokens to read, how sizes become CSS, which component CSS to emit, and which packages and features are on. This page explains how the file is found and read; every key is listed in the systhema.config reference.

A typical configLink to this section

import type { SysthemaConfig } from '@systhemaui/core'
import manifest from './src/tokens/manifest.json'

const config: SysthemaConfig = {
  manifest,
  packages: {
    react: {
      enabled: true,
      transitionClasses: 'duration-300 ease-out-cubic',
      animationClasses: 'aos animate-fadeinup',
    },
  },
}

export default config

Every key is optional. Without a config file, or without a manifest, Systhema uses the default tokens that ship with @systhemaui/core.

In an HTML project without TypeScript, write the same object in systhema.config.js:

const manifest = require('./src/tokens/manifest.json')

/** @type {import('@systhemaui/core').SysthemaConfig} */
module.exports = {
  manifest,
  packages: { react: false },
}

Where the config is loaded fromLink to this section

@systhemaui/core uses the first file it finds, in this order:

1. systhema.config.ts
2. systhema.config.js
3. systhema.config.json
4. src/systhema.config.ts
5. src/systhema.config.js
6. src/systhema.config.json

How it is readLink to this section

• Merged with defaults. Your object is deep-merged over Systhema's default config, so you set only what differs. manifest is the exception: when you set one, it replaces the default manifest instead of merging with it.
• At build time. The Tailwind plugin and systhema-core sync read the config to generate CSS, types and references. After changing manifest, customTokens, spacing or blocks, run pnpm sync and restart the dev server.
• On the server. Components and your server code read it through getSysthemaConfigSync() or getSysthemaConfig().
• In the browser. The config file is never bundled. SysthemaProvider hands the browser the config together with a small snapshot of resolved token values, and client components read them from @systhemaui/core/client. See Client and server code.

What each section controlsLink to this section

packagesLink to this section

packages turns on the integrations a project uses. Both are off by default:

• react: true, or an object with enabled, transitionClasses and animationClasses. Turning it on adds the component classes to the safelist so Tailwind keeps them. transitionClasses go on interactive elements (buttons, links, cards) and animationClasses on elements that reveal as they scroll in; see Motion.
• payload: true in a Payload project. Payload itself is configured with withSysthema() in payload.config.ts; see withSysthema.

The package flags should match the @systhemaui/* packages in package.json. See Choosing packages.

Reading the config at runtimeLink to this section

Use getSysthemaConfigSync() or the async getSysthemaConfig() to read the merged config from your own server code, and import them from @systhemaui/core/client in a client component. See Runtime config.

import { getSysthemaConfigSync } from '@systhemaui/core'

const { packages } = getSysthemaConfigSync()

RelatedLink to this section

• systhema.config reference
• Design tokens
• Responsive sizing