How To Use Rules

Once you’ve created HTTP rules, you need to integrate them into your API projects. This guide covers loading rules, configuration, and common usage patterns.

Loading Rules

There are two ways to load rules into Thymian:

1. Via Configuration File

Create a thymian.config.yaml file in your project root:

ruleSets:
  - '@thymian/rules-rfc-9110' # a rule-set package (npm)
  - './rules/my-api.rule.ts' # a local rule file (explicit extension)

plugins:
  '@thymian/plugin-http-linter': {}

A ruleSets: entry is a rule-set package name or a local path with an explicit extension — the same bare-vs-local contract as --rule-set (below). What it is not is a glob: ./rules/**/*.rule.ts will not expand here. To pull in many local files at once, bundle them into a rule set that globs them through its pattern: field.

2. Via CLI flags

# a published rule-set package
npx thymian lint --rule-set @thymian/rules-rfc-9110

# a local rule or rule-set entry point (explicit extension, not a glob)
npx thymian lint --rule-set ./rules/my-api.rule.ts

Creating Your Own Rule Set

File Structure

Organize your rule set as an npm package:

my-api-rules/
├── package.json
├── src/
│   ├── index.ts
│   └── rules/
│       ├── authentication/
│       │   └── require-bearer-token.rule.ts
│       ├── headers/
│       │   └── require-correlation-id.rule.ts
│       └── versioning/
│           └── check-api-version.rule.ts
└── tsconfig.json

Package Definition

package.json:

{
  "name": "@mycompany/api-rules",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "peerDependencies": {
    "@thymian/plugin-http-linter": "^0.0.1",
    "@thymian/core": "^0.0.1"
  }
}

Rule Set Entry Point

src/index.ts:

import type { RuleSet } from '@thymian/core';

const myCompanyRules: RuleSet = {
  name: '@mycompany/api-rules',
  url: 'https://api-guidelines.mycompany.com',
  pattern: 'rules/**/*.rule.js', // Glob pattern for built rules
};

export default myCompanyRules;

A published rule set ships built JavaScript — its entry point (main above) is resolved as a bare specifier, and a package that ships unbuilt TypeScript source is declined. The glob pattern here matches the rule set’s own compiled output under dist/, not src/. See Loading Rules and Plugins for the full contract.

Using Your Rule Set

After publishing your rule set to npm, install it in your project:

npm install @mycompany/api-rules

ruleSets:
  - '@mycompany/api-rules'

List Loaded Rules

See which rules are loaded:

thymian rules list

Or with specific rule sources:

thymian rules list --rule-set ./rules/my-api.rule.ts

Troubleshooting

Rules Not Loading

Problem: Rules aren’t being loaded

Solutions:

1. Check the glob pattern matches your files:

ls -la ./rules/**/*.rule.ts

2. Verify the rule exports default:

export default httpRule('...'); // ✅ Correct
export const myRule = httpRule('...'); // ❌ Wrong

3. Check the specifier itself — the most common causes are:

   • A missing explicit extension. --rule-set ./my-rule does not resolve; write --rule-set ./my-rule.ts.
   • A bare specifier that was meant to be local. There is no <cwd>/<specifier> fallback — write it as a path (./my-rule.ts), not a bare name.
   • .mts, .cts, or .d.ts. None of these are loadable — use .ts.

   See Loading Rules and Plugins for the full contract.

Note

Loading never type-checks — jiti strips TypeScript types, it does not check them. A rule can load successfully and still contain type errors. Run tsc --noEmit in CI to catch those; it is a separate concern from whether the rule loads.

Next Steps

• Explore the CLI commands for managing rules
• Learn about creating custom rules
• See combining rule types for hybrid validation