Path Filtering

Cerial lets you control which .cerial files are processed during generation. You can exclude drafts, vendor schemas, test fixtures, or anything else you don't want in your generated client.

Three mechanisms work together: config fields, .cerialignore files, and a cascading resolution order.

Filter Fields

All three filter fields accept arrays of glob patterns (.gitignore-style syntax).

These fields are available on CerialConfig (root level), SchemaEntry (per-schema), and FolderConfig (folder-level configs).

.cerialignore File

Place a .cerialignore file at your project root or inside a schema folder to exclude files using .gitignore-style syntax.

Syntax

• Lines starting with # are comments
• ! negates a pattern (re-includes a previously excluded path)
• Trailing / matches directories
• ** matches recursively across directories
• Standard glob wildcards (*, ?, [...]) work as expected

Example

# Exclude draft schemas
drafts/

# Exclude generated files
**/generated/

# But keep this specific file
!drafts/important.cerial

Scope

• A .cerialignore at the project root applies to all schemas, even when using the -s flag.
• A .cerialignore inside a schema folder only affects that folder's schemas.

Both can coexist. Root-level patterns apply first, then folder-level patterns layer on top.

Cascade Priority

When multiple filter sources exist, Cerial resolves them in this order:

A file starts as included. Each level can exclude it. The matching include at that level can rescue it. But if any ignore pattern matches, the file is gone for good.

Config Examples

Root-Level Filtering

Exclude test fixtures across all schemas:

import { defineConfig } from 'cerial';

export default defineConfig({
  schemas: {
    auth: { path: './schemas/auth' },
    cms: { path: './schemas/cms' },
  },
  exclude: ['**/test-fixtures/**'],
});

Per-Schema Filtering

Each schema entry can have its own filter patterns:

import { defineConfig } from 'cerial';

export default defineConfig({
  schemas: {
    auth: {
      path: './schemas/auth',
      exclude: ['**/*.draft.cerial'],
    },
    cms: {
      path: './schemas/cms',
      exclude: ['internal/**'],
      include: ['internal/public-api.cerial'],
    },
  },
  exclude: ['**/test-fixtures/**'],
});

The cms schema excludes everything under internal/ except internal/public-api.cerial, which is rescued by include.

Folder-Level Config Filtering

Folder configs support the same filter fields:

// schemas/auth/cerial.config.ts
export default {
  output: './client',
  exclude: ['deprecated/**'],
};

Patterns in folder configs are relative to the folder directory.

Common Use Cases

Exclude draft or experimental schemas:

exclude: ['**/*.draft.cerial', '**/experimental/**']

Exclude vendor or third-party schemas:

ignore: ['vendor/**', 'third-party/**']

Exclude test fixtures from generation:

exclude: ['**/test-fixtures/**', '**/fixtures/**']

Include specific files from an otherwise excluded directory:

exclude: ['legacy/**'],
include: ['legacy/still-needed.cerial']

Gotchas

Parent-directory negation doesn't work in .cerialignore

Writing dir/ then !dir/keep.cerial in the same .cerialignore won't rescue the file. This is standard .gitignore behavior: once a parent directory is excluded, negating a child inside it has no effect.

Use config include instead:

exclude: ['dir/**'],
include: ['dir/keep.cerial']

include is not a standalone whitelist

include only overrides exclusions. If nothing is excluded, include does nothing. You can't use include alone to say "only process these files."

Pattern relativity

Patterns are always relative to their scope:

• Root config patterns are relative to the project root
• Schema entry patterns are relative to the schema path
• Folder config patterns are relative to the folder

No ../ escaping

Patterns cannot escape their scope directory. A pattern like ../other-schema/*.cerial is rejected during validation.

No CLI flags for filtering

Filtering is config-only. There are no --ignore, --exclude, or --include CLI flags. All filter rules live in your config file or .cerialignore files.

cerial init

The cerial init command offers to create a .cerialignore file with sensible defaults when scaffolding your project config.