Configuration

Pencel is zero-config by default—you can start building Web Components without any configuration. For advanced features like Sass, custom namespaces, or framework outputs, use a pencel.config.ts file.

Setup

First, install the Pencel CLI:

npm

npm install -D @pencel/cli

pnpm

pnpm add -D @pencel/cli

yarn

yarn add -D @pencel/cli

bun

bun add -D @pencel/cli

Then create a pencel.config.ts in your project root:

pencel.config.ts

import { defineConfig } from '@pencel/cli';

export default defineConfig({
  input: {
    qualifier: 'pen'        // Find files matching *.pen.ts
  },
  output: {
    qualifier: 'gen'        // Output files as *.gen.ts
  },
  baseDir: 'src',           // Base directory for discovery
  plugins: [                // Core and output plugins
    'css',
    // Framework output plugins would go here too
  ],
  runtime: {
    tagNamespace: 'my'      // Component tags prefixed with 'my-'
  }
});

Tip

Use defineConfig for full TypeScript support and autocomplete in your editor.

Configuration Options

input.qualifier – Pattern for discovering component files (default: "pen")
Files matching *.pen.ts are treated as Pencel components.

output.qualifier – Pattern for generated output files (default: "gen")
Compiled components are written as *.gen.ts next to source files.

baseDir – Base directory for file discovery (default: "src")

tsconfig – Path to your TypeScript config (default: "tsconfig.json")

plugins – Array of plugins to enable. Plugins include core plugins (CSS, SCSS) and output plugins that generate framework-specific code. Each plugin can specify where to write its output via outputPath or similar options.
See Plugins for available options.

runtime.tagNamespace – Global namespace prefix for all component tags (default: "pen")
Set to "my" to generate tags like my-button, my-card, etc.

Integration with Your Build System

Note

A Vite plugin for Pencel may be added in the future. For now, run pencel compile before you build.

Build Integration

NPM Scripts

Add a build script to your package.json:

{
  "scripts": {
    "build": "pencel compile"
  }
}

Then run:

npm run build

Nx Workspace

For monorepos using Nx, create a pencel.config.ts and reference it in your project.json:

{
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "options": {
        "command": "pencel compile --config pencel.config.ts"
      }
    }
  }
}

Or configure Pencel as an Nx plugin for automatic project graph integration.

Plugins with Output Configuration

Plugins can specify where their output should be written. For example, a React plugin would generate React wrapper components:

pencel.config.ts

import { defineConfig } from '@pencel/cli';

export default defineConfig({
  input: {
    qualifier: 'pen'
  },
  output: {
    qualifier: 'gen'
  },
  plugins: [
    'css',
    {
      name: 'react',
      outputPath: './src/generated/react'
    }
  ]
});

The react plugin will generate React wrapper components in the specified outputPath. See Plugins for available plugins and their output options.