Configuration Reference

Coralite projects are configured using a coralite.config.js file placed at the root directory of your project.

1. The coralite.config.js File #

Use the defineConfig helper exported from coralite to construct and validate your project configuration:

  import { defineConfig } from 'coralite'
  
  export default defineConfig({
    output: 'dist',
    components: 'src/components',
    pages: 'src/pages',
    public: 'public',
    cleanUrls: true,
    viewTransitions: true,
    mode: 'production'
  })

2. Required Keys #

Every Coralite application requires three path configuration keys:

Key	Type	Description
`output`	`string`	Path to the destination directory where compiled static files are emitted (e.g. `'dist'`).
`components`	`string`	Path to the directory containing Coralite Web Components (e.g. `'src/components'`).
`pages`	`string`	Path to the directory containing application pages (e.g. `'src/pages'`).

3. Core Options #

Core options control asset delivery, URL routing formats, view transitions, and build modes:

Option	Type	Default	Description
`public`	`string`	`'public'`	Directory containing static assets copied directly to the build root.
`cleanUrls`	`boolean`	`true`	When `true`, outputs directory-style clean URLs (e.g. `/about/index.html` at route `/about`). When `false`, outputs file-style URLs (e.g. `/about.html`).
`viewTransitions`	`boolean`	`true`	Enables native Same-Document View Transitions for client navigation.
`mode`	`'production' \| 'development' \| 'testing'`	`'production'`	Build and execution environment mode.

4. Extended Options #

Extended configuration options allow declaring global store state, injecting stylesheets, registering plugins, and setting Content Security Policies:

store — Object declaring initial default values for the signal-backed global store.
javascript
Code copied!
```
  store: {
    theme: 'dark',
    user: { name: 'Alex' }
  }
```
externalStyles — Array of external stylesheet URLs or paths injected into every page.
javascript
Code copied!
```
  externalStyles: [
    'https://cdn.example.com/styles.css',
    '/css/theme.css'
  ]
```
plugins — Array of configured plugin instances created via definePlugin. Contexts defined in server.context and client.context are automatically injected into Component and Page handlers (server() and client()). Plugin context is never injected into isomorphic getters.
javascript
Code copied!
```
  plugins: [
    myPlugin({ apiKey: 'secret-key' })
  ]
```

csp — Content Security Policy rules and options.

  csp: {
    enabled: true,
    hashAlgorithm: 'sha256',
    injectMeta: true,
    directives: {
      'default-src': ["'self'"],
      'script-src': ["'self'"]
    }
  }

5. Asset Injection #

The assets configuration array manages third-party library assets, copying files to the output directory and optionally injecting <script>, <link>, or <meta> tags with Subresource Integrity (SRI) hashes:

  import { defineConfig } from 'coralite'
  
  export default defineConfig({
    output: 'dist',
    components: 'src/components',
    pages: 'src/pages',
    assets: [
      {
        src: 'node_modules/lib/dist/lib.js',
        dest: 'assets/js/lib.js',
        inject: {
          type: 'script',
          placement: 'head-end',
          sri: true
        }
      }
    ]
  })

The inject option object supports configuration properties:

type — 'script', 'link', or 'meta'.
placement — 'head-start', 'head-end', 'body-start', or 'body-end'.
sri — Boolean or hash algorithm ('sha256', 'sha384', 'sha512') to calculate and attach Subresource Integrity attributes.

6. Test Fixtures & Page Exclusions #

To prevent test fixture pages from polluting your pages directory or ending up in production builds, configure the fixtures and exclude options:

  import { defineConfig } from 'coralite'
  
  export default defineConfig({
    output: 'dist',
    components: 'src/components',
    pages: 'src/pages',
  
    // Directory containing component test fixture pages:
    fixtures: 'tests/fixtures',
  
    // Or advanced configuration with fixture-only components and route prefix:
    // fixtures: {
    //   pages: 'tests/fixtures/pages',
    //   components: 'tests/fixtures/components',
    //   prefix: '/__fixtures__'
    // },
  
    // Optional glob patterns to exclude from page discovery:
    exclude: ['**/drafts/**']
  })

Key behaviors:

Production build isolation: During coralite build, fixture pages and common test patterns (__test__, __tests__, *.test.html, *.spec.html, *.fixture.html) are automatically excluded and never emitted to dist.
Dev and test servers: Running coralite dev or coralite test mounts your test fixtures under /__fixtures__/<fixture-name> with full component SSR, scoping, and live reload.