GitHub v1.3.1

Configuration Reference

Reference

Complete reference for coralite.config.js configuration options, including required directories, core options, extended state, CSP rules, and static asset injection.

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:

javascript
Code copied!
  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.
    javascript
    Code copied!
      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:

javascript
Code copied!
  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:

javascript
Code copied!
  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.