@codedrifters/configulator
v0.0.127
Published
Projen configs frequently used in CodeDrifter projects.
Readme
Configulator
A library of Projen components used by CodeDrifters to manage repository configuration across various projects. Configulator extends standard Projen configurations with our preferred defaults and provides company-specific components and workflows.
Table of Contents
- Overview
- What is Projen?
- What is Configulator?
- Project Types
- Usage Patterns
- Configuration Options
- Turbo Repo
- PNPM Workspace
- Updating VERSION constants
- File Management Rules
- Workflow Tips
- API Reference
- Troubleshooting
- Additional Resources
Overview
This guide explains the core infrastructure tools used in our projects: Projen and Configulator. These tools help us maintain consistency across multiple projects and reduce repetitive setup work.
What is Projen?
Projen is a project generator and configuration management tool that:
- Creates standardized project structures
- Manages configuration files programmatically
- Handles dependency updates automatically
- Provides consistent build workflows
Key Concepts
Components: Individual pieces of configuration (e.g., Jest, Vitest, Prettier, TypeScript). Each component configures specific files and settings. When you add or remove a component, all its associated files and configurations are automatically managed.
Project Types: Base-level configurations for different kinds of projects (e.g., TypeScript app, monorepo, React project).
Synthesis: The process of generating actual files from your configuration. Run npx projen to synthesize your project.
What is Configulator?
Configulator is CodeDrifters' custom extension of Projen. It:
- Extends standard Projen configurations with our preferred defaults
- Provides company-specific components and workflows
- Available as an npm package:
@codedrifters/configulator
Why We Built It
Instead of setting up each new project from scratch (90% identical setup repeated), Configulator lets us:
- Generate consistent project structures
- Pick and choose components we need
- Maintain standardized tooling across all projects
- Receive updates to common configurations automatically
Project Types
Configulator provides two main project types designed for monorepo workflows:
MonorepoProject
MonorepoProject extends Projen's TypeScriptAppProject and is designed specifically for monorepo root projects. It provides all the infrastructure needed to manage a monorepo with multiple sub-projects.
When to Use It
Use MonorepoProject for:
- Root-level monorepo configuration
- Managing workspace-wide settings (PNPM, Turborepo, VS Code)
- Defining shared dependency catalogs
- Configuring build workflows for the entire monorepo
Key Features
- PNPM Workspace Management: Automatically generates and manages
pnpm-workspace.yaml - Turborepo Integration: Built-in support for Turborepo with remote caching capabilities
- VS Code Configuration: Automatic VS Code settings for consistent development experience
- Default Catalog: Pre-configured catalog of common dependency versions (AWS CDK, Projen, Constructs, Turbo)
- Build Workflow Configuration: GitHub Actions workflows with Turborepo support
- TypeScript Configuration: Pre-configured TypeScript with sensible defaults
Basic Example
import { MonorepoProject } from '@codedrifters/configulator';
const project = new MonorepoProject({
name: 'my-monorepo'
});
project.synth();Advanced Example with Remote Cache
import { MonorepoProject } from '@codedrifters/configulator';
const project = new MonorepoProject({
name: 'my-monorepo',
turboOptions: {
remoteCacheOptions: {
profileName: 'profile-prod-000000000000-us-east-1',
oidcRole: 'arn:aws:iam::000000000000:role/TurborepoRemoteCachingRole',
endpointParamName: '/TURBOREPO/ENDPOINT/PARAMETER',
tokenParamName: '/TURBOREPO/TOKEN/PARAMETER',
teamName: 'prod',
},
},
pnpmOptions: {
pnpmWorkspaceOptions: {
onlyBuiltDependencies: ['@swc/core', 'esbuild', 'unrs-resolver'],
},
},
});
project.synth();Configuration Options
The MonorepoProject accepts all options from TypeScriptProjectOptions plus:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| name | string | Required | Project name |
| turbo | boolean | true | Enable Turborepo support |
| turboOptions | TurboRepoOptions | undefined | Turborepo configuration including remote cache options |
| pnpmOptions.version | string | VERSION.PNPM_VERSION | PNPM version to use |
| pnpmOptions.pnpmWorkspaceOptions | PnpmWorkspaceOptions | See below | PNPM workspace configuration |
Default Behavior:
projenrcTs: true- Uses TypeScript for projen configurationprettier: true- Enables Prettier formattinglicensed: false- No license by defaultsampleCode: false- No sample code generatedjest: false- Jest disabled at root levelrelease: false- Root project is not releaseddepsUpgrade: false- No automatic dependency upgrades at rootdisableTsconfigDev: true- No tsconfig.dev.json at rootpackageManager: NodePackageManager.PNPM- PNPM is mandatorydefaultReleaseBranch: "main"- Standard branch name
Pull Request Linting:
- By default, pull request titles are validated to follow Conventional Commits
- All conventional commit types are allowed by default:
feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert - This provides flexibility for different types of changes while maintaining consistency
Overriding Pull Request Lint Options:
To customize which commit types are allowed, override the githubOptions.pullRequestLintOptions:
const project = new MonorepoProject({
name: 'my-monorepo',
githubOptions: {
pullRequestLintOptions: {
semanticTitleOptions: {
types: ['feat', 'fix', 'docs', 'chore'], // Only allow these types
},
},
},
});You can also configure other pull request linting options:
const project = new MonorepoProject({
name: 'my-monorepo',
githubOptions: {
pullRequestLintOptions: {
semanticTitleOptions: {
types: ['feat', 'fix', 'docs'],
requireScope: true, // Require scope in commit type (e.g., feat(ui):)
scopes: ['ui', 'api', 'core'], // Only allow these scopes
},
},
},
});The root project automatically includes @codedrifters/configulator and constructs as dev dependencies.
TypeScriptProject
TypeScriptProject extends Projen's TypeScriptProject with CodeDrifters defaults. It's designed for sub-projects within a monorepo or standalone TypeScript projects.
When to Use It
Use TypeScriptProject for:
- Sub-projects within a monorepo (most common use case)
- Standalone TypeScript libraries or applications
- Packages that will be published to NPM
- Projects that need consistent testing, linting, and build configuration
Key Features
- Automatic PNPM Version Inheritance: Inherits PNPM version from parent
MonorepoProjectwhen used as a sub-project - Configurable Test Runner: Choose Jest (default) or Vitest via the
testRunneroption. Jest uses@swc/jestfor fast execution; Vitest uses a generatedvitest.config.tswith coverage and watch tasks. - Prettier Integration: Automatic Prettier configuration
- Automatic Turborepo Integration: Automatically configures Turborepo tasks when parent has TurboRepo enabled
- Catalog Dependency Support: Can use catalog dependencies defined in parent workspace
- Release Support: Built-in support for NPM releases with continuous deployment triggers
Basic Example
import { MonorepoProject, TypeScriptProject } from '@codedrifters/configulator';
// Root project
const root = new MonorepoProject({
name: 'my-monorepo'
});
// Sub-project
const myPackage = new TypeScriptProject({
name: 'my-package',
packageName: '@myorg/my-package',
outdir: 'packages/my-package',
parent: root,
description: 'My awesome package',
deps: ['some-dependency'],
devDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
});
root.synth();Example with Release Configuration
import { MonorepoProject, TypeScriptProject } from '@codedrifters/configulator';
const root = new MonorepoProject({
name: 'my-monorepo'
});
const constructs = new TypeScriptProject({
name: '@codedrifters/constructs',
packageName: '@codedrifters/constructs',
outdir: 'packages/@codedrifters/constructs',
description: 'Constructs frequently used in CodeDrifter projects.',
repository: 'https://github.com/codedrifters/packages',
authorName: 'CodeDrifters',
authorOrganization: true,
licensed: false,
parent: root,
deps: [
'@aws-sdk/client-dynamodb',
'@types/aws-lambda',
'change-case@^4.0',
'type-fest@^4',
],
devDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
peerDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
release: true,
releaseToNpm: true,
});
root.synth();Parent-Child Relationship
When TypeScriptProject is created with a parent that is a MonorepoProject:
- PNPM Version: Automatically inherits the PNPM version from the parent
- Workspace Integration: Automatically added to the parent's PNPM workspace
- Turborepo Integration: If parent has Turborepo enabled, the sub-project automatically gets Turborepo task configuration
- Catalog Dependencies: Can reference catalog dependencies defined in the parent's workspace
- Dependency Upgrade Exclusions: Automatically excludes catalog-managed dependencies from upgrade workflows
Configuration Options
The TypeScriptProject accepts all options from Projen's TypeScriptProjectOptions with these defaults:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| name | string | Required | Project name |
| packageName | string | Same as name | NPM package name |
| outdir | string | "." | Output directory (required for sub-projects) |
| parent | MonorepoProject | undefined | Parent monorepo project (recommended) |
| defaultReleaseBranch | string | "main" | Default release branch |
| packageManager | NodePackageManager | PNPM | Package manager (always PNPM) |
| prettier | boolean | true | Enable Prettier |
| sampleCode | boolean | false | Generate sample code |
| release | boolean | false | Enable NPM releases |
| licensed | boolean | false | Include license (unless license option provided) |
| testRunner | TestRunner | TestRunner.JEST | Test runner: TestRunner.JEST or TestRunner.VITEST |
| vitestOptions | VitestOptions | undefined | Options for Vitest (only used when testRunner is TestRunner.VITEST) |
Test runner (Jest or Vitest):
- Jest (default): External
jest.config.json,@swc/jestfor fast compilation, test files insrc/. Use when you want to keep existing Jest-based workflows. - Vitest: Set
testRunner: TestRunner.VITESTto use Vitest. The project gets a generatedvitest.config.ts,vitest(and optionally@vitest/coverage-v8) as devDeps, and tasks:test(runsvitest run),test:watch. Snapshots are updated automatically on each test run to match the project's previous Jest behavior (no separate snapshot-update step). Coverage directory is added to.gitignoreand.npmignore. Jest is disabled (jest: false) when Vitest is selected; the two cannot be used together.
NPM Ignore:
- Automatically ignores
*.spec.*,*.test.*, and__fixtures__patterns
Release Configuration:
- Uses continuous release trigger
- Only releases when package directory content changes
- Release path based on
outdir
Usage Patterns
Monorepo Setup Pattern
The most common pattern is to create a monorepo with a root project and multiple sub-projects:
- Create the root project using
MonorepoProject:
// projenrc/root-project.ts
import { MonorepoProject } from '@codedrifters/configulator';
export const configureRootProject = () => {
const project = new MonorepoProject({
name: 'my-monorepo',
turboOptions: {
remoteCacheOptions: {
profileName: 'my-profile',
oidcRole: 'arn:aws:iam::123456789012:role/TurborepoRole',
endpointParamName: '/TURBOREPO/ENDPOINT',
tokenParamName: '/TURBOREPO/TOKEN',
teamName: 'my-team',
},
},
});
return project;
};- Add sub-projects using
TypeScriptProject:
// projenrc/my-package.ts
import { MonorepoProject } from '@codedrifters/configulator';
import { TypeScriptProject } from '@codedrifters/configulator';
export const configureMyPackage = (parent: MonorepoProject) => {
const myPackage = new TypeScriptProject({
name: 'my-package',
packageName: '@myorg/my-package',
outdir: 'packages/my-package',
description: 'My package description',
parent,
deps: ['dependency-1', 'dependency-2'],
devDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
});
return { myPackage };
};- Wire everything together in your main projenrc file:
// .projenrc.ts or projenrc/index.ts
import { configureRootProject } from './projenrc/root-project';
import { configureMyPackage } from './projenrc/my-package';
const root = configureRootProject();
const { myPackage } = configureMyPackage(root);
root.synth();Standalone Project Pattern
You can also use TypeScriptProject without a parent for standalone projects:
import { TypeScriptProject } from '@codedrifters/configulator';
const project = new TypeScriptProject({
name: 'standalone-project',
packageName: '@myorg/standalone-project',
description: 'A standalone TypeScript project',
deps: ['some-dependency'],
});
project.synth();Note: Without a parent, the project will use the default PNPM version from Configulator's version constants.
Dependency Management
⚠️ Important: All dependencies must be configured through Projen configuration files (
.projenrc.tsorprojenrc/*.ts), never by manually running package manager commands likenpm install,pnpm add, oryarn add. Manual installation will create conflicts with Projen-managed files and may be overwritten when you runnpx projen.
Using Catalog Dependencies
The MonorepoProject automatically sets up a default catalog with common dependencies:
// Defined in MonorepoProject defaults
defaultCatalog: {
'aws-cdk': VERSION.AWS_CDK_CLI_VERSION,
'aws-cdk-lib': VERSION.AWS_CDK_LIB_VERSION,
'projen': VERSION.PROJEN_VERSION,
'constructs': VERSION.AWS_CONSTRUCTS_VERSION,
'turbo': VERSION.TURBO_VERSION,
}Sub-projects can reference these using the catalog: protocol:
const myPackage = new TypeScriptProject({
// ... other options
devDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
peerDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
});Workspace Dependencies
Sub-projects can depend on other packages in the same monorepo:
const packageB = new TypeScriptProject({
// ... other options
deps: ['@myorg/package-a@workspace:*'],
});Custom Catalog
You can also define custom catalogs in the MonorepoProject:
const root = new MonorepoProject({
name: 'my-monorepo',
pnpmOptions: {
pnpmWorkspaceOptions: {
defaultCatalog: {
'react': '^18.0.0',
'typescript': '^5.0.0',
},
namedCatalogs: {
frontend: {
'react': '^18.0.0',
'react-dom': '^18.0.0',
},
backend: {
'express': '^4.18.0',
},
},
},
},
});Then reference them in sub-projects:
// Default catalog
deps: ['react@catalog:react']
// Named catalog
deps: ['react@catalog:frontend/react']Updating VERSION constants
The catalog versions (e.g. VERSION.PROJEN_VERSION, VERSION.TURBO_VERSION) in src/versions.ts can be updated automatically so they stay in sync with npm releases while respecting the PNPM workspace minimumReleaseAge (so only versions published long enough ago are considered).
What it does
- A script (
scripts/update-versions.tsat monorepo root) fetches the latest eligible version for each npm-backed constant from the npm registry using thetimefield. - Only versions that have been published for at least
minimumReleaseAgeminutes (from the PNPM workspace) are considered. - The script runs as part of the upgrade task, so when the upgrade workflow runs (e.g. nightly or
workflow_dispatch), version updates are included in the same PR as dependency upgrades.
How to run
From the monorepo root:
- Propose only (print suggested changes, do not edit files):
pnpm run update-versions - Apply locally (update
versions.tsand runnpx projen):pnpm run update-versions -- --apply - In CI: When run from the upgrade workflow, the script auto-applies when there are updates so changes are included in the upgrade PR.
Adding a new npm-backed constant
- Add the constant to
src/versions.ts(e.g.MY_PACKAGE_VERSION: "1.0.0"). - Add an entry to
VERSION_NPM_PACKAGESinsrc/version-package-map.ts:
Constants not listed in{ key: "MY_PACKAGE_VERSION", npmPackage: "my-package" },VERSION_NPM_PACKAGES(e.g.NODE_WORKFLOWS) are skipped by the update script.
Turborepo Integration
When you create a MonorepoProject with turbo: true (the default), Turborepo is automatically configured. Sub-projects created with TypeScriptProject automatically get Turborepo task configuration if their parent has Turborepo enabled.
The integration includes:
- Automatic task definitions (compile, test, package)
- Output directory configuration (
dist/**,lib/**) - Remote cache support (when configured)
- Build workflow integration
See the Turbo Repo section for more details.
Configuration Options
MonorepoProjectOptions
Extends TypeScriptProjectOptions with:
interface MonorepoProjectOptions {
name: string; // Required
turbo?: boolean; // Default: true
turboOptions?: TurboRepoOptions;
pnpmOptions?: {
version?: string;
pnpmWorkspaceOptions?: PnpmWorkspaceOptions;
};
upgradeConfigulatorTask?: boolean; // Default: false — see below
upgradeConfigulatorTaskOptions?: UpgradeDependenciesOptions;
// ... all TypeScriptProjectOptions
}Configulator upgrade workflow (default: off)
By default, MonorepoProject does not add a separate workflow that upgrades only @codedrifters/configulator. Monorepos that use configulator should rely on projen's built-in upgrade workflow for all dependency upgrades (including configulator), so there is one source of truth and no duplicate or conflicting automation.
To opt in to a dedicated scheduled workflow that upgrades only @codedrifters/configulator (e.g. nightly), set upgradeConfigulatorTask: true and optionally customize with upgradeConfigulatorTaskOptions (schedule, etc.):
const project = new MonorepoProject({
name: 'my-monorepo',
upgradeConfigulatorTask: true,
upgradeConfigulatorTaskOptions: {
workflowOptions: { schedule: UpgradeDependenciesSchedule.DAILY },
},
});TypeScriptProjectOptions
Extends Projen's TypeScriptProjectOptions with CodeDrifters defaults. See the TypeScriptProject section for details.
TurboRepoOptions
interface TurboRepoOptions {
turboVersion?: string;
remoteCacheOptions?: RemoteCacheOptions;
extends?: Array<string>;
globalDependencies?: Array<string>;
globalEnv?: Array<string>;
globalPassThroughEnv?: Array<string>;
ui?: 'tui' | 'stream';
envMode?: string;
// ... and more
}
interface RemoteCacheOptions {
profileName: string;
oidcRole: string;
endpointParamName: string;
tokenParamName: string;
teamName: string;
}PnpmWorkspaceOptions
interface PnpmWorkspaceOptions {
fileName?: string; // Default: 'pnpm-workspace.yaml'
minimumReleaseAge?: number; // Minutes, default: ONE_DAY (1440)
minimumReleaseAgeExclude?: Array<string>; // Default: ['@codedrifters/*']
onlyBuiltDependencies?: Array<string>;
ignoredBuiltDependencies?: Array<string>;
subprojects?: Array<string>;
defaultCatalog?: { [key: string]: string };
namedCatalogs?: { [catalogName: string]: { [dependencyName: string]: string } };
}Turbo Repo
What It Does
Turbo Repo is a build system for monorepos that:
- Caches build outputs intelligently
- Only rebuilds what changed
- Speeds up CI/CD significantly
- Works with remote caching
How It Works
Hashing: All input files (source code, configs) are hashed
Cache Check: If inputs haven't changed, cached outputs are reused
Smart Rebuilds: Only affected packages rebuild when dependencies change
Remote Cache: Build outputs stored in S3 (not Vercel) for team sharing
Configuration
Turborepo is automatically enabled in MonorepoProject (can be disabled with turbo: false). Configure it using the turboOptions:
const project = new MonorepoProject({
name: 'my-monorepo',
turboOptions: {
remoteCacheOptions: {
profileName: 'my-profile',
oidcRole: 'arn:aws:iam::123456789012:role/TurborepoRole',
endpointParamName: '/TURBOREPO/ENDPOINT',
tokenParamName: '/TURBOREPO/TOKEN',
teamName: 'my-team',
},
},
});Running Locally
Before using Turbo Repo locally, you need AWS credentials:
# Run the login script (credentials last ~8 hours)
./scripts/aws-profile-turbo-repo.shCommon Error: If you get a "gRPC error" when running Turbo first thing in the morning, the Lambda function is cold. Just run the command again - it will work the second time.
Benefits
- Fast CI: Builds can complete in under a minute when using cached outputs
- Selective Rebuilds: Only changed code rebuilds, not the entire monorepo
- Local + CI Sharing: Cache between your machine and GitHub Actions
PNPM Workspace
The MonorepoProject automatically generates and manages pnpm-workspace.yaml. This file:
- Lists all sub-projects in the
packagesarray - Configures PNPM settings like
minimumReleaseAgeandonlyBuiltDependencies - Defines dependency catalogs for version management
Workspace Structure
The workspace file is auto-generated and lists all sub-projects:
packages:
- 'packages/package-a'
- 'packages/package-b'
- 'apps/frontend'Sub-projects are automatically discovered from project.subprojects and any additional paths specified in pnpmWorkspaceOptions.subprojects.
Configuration
Configure the workspace through pnpmOptions.pnpmWorkspaceOptions:
const project = new MonorepoProject({
name: 'my-monorepo',
pnpmOptions: {
pnpmWorkspaceOptions: {
minimumReleaseAge: MIMIMUM_RELEASE_AGE.ONE_DAY,
minimumReleaseAgeExclude: ['@codedrifters/*'],
onlyBuiltDependencies: ['@swc/core', 'esbuild'],
defaultCatalog: {
'react': '^18.0.0',
},
},
},
});File Management Rules
DO NOT Edit These Files Directly
Projen manages many files automatically. Never edit these files by hand:
- Configuration files (
.prettierrc,tsconfig.json, etc.) - GitHub workflows (
.github/workflows/*) - Build scripts
- Most files listed in
.projen/files.json
Exception: package.json
package.json is special - Projen reads, modifies, and writes it back, preserving some manual changes. However, you should still manage dependencies through Projen config, not by editing package.json directly.
Adding Dependencies
WRONG:
npm install some-packageCORRECT: Add dependencies in your .projenrc.ts configuration and run npx projen.
const project = new TypeScriptProject({
// ... other options
deps: ['some-package'],
});Workflow Tips
Before Committing
Run Turbo build locally (from monorepo root) to cache everything:
# This caches outputs that GitHub Actions can reuse
pnpm build:allThen commit and push. Your GitHub build will be much faster.
Adding New Packages
- Create a new configuration file in
projenrc/(e.g.,projenrc/new-package.ts) - Export a function that creates a
TypeScriptProjectwith the parent as a parameter - Import and call it in your main projenrc file
- Run
npx projento regenerate configs - Commit the changes
Example:
// projenrc/new-package.ts
import { MonorepoProject, TypeScriptProject } from '@codedrifters/configulator';
export const configureNewPackage = (parent: MonorepoProject) => {
return new TypeScriptProject({
name: 'new-package',
packageName: '@myorg/new-package',
outdir: 'packages/new-package',
parent,
deps: ['dependency'],
});
};Updating Configulator
To receive updates from Configulator in your project:
- Update the version in your projenrc definition file
- Run
npx projen - Review and test changes
- Commit
API Reference
MonorepoProject
Constructor:
new MonorepoProject(options: MonorepoProjectOptions)Key Properties:
pnpmVersion: string- The PNPM version used by the monorepo
Key Methods:
- Inherits all methods from
TypeScriptAppProject
TypeScriptProject
Constructor:
new TypeScriptProject(options: TypeScriptProjectOptions)Key Methods:
addDeps(...deps: string[])- Add runtime dependenciesaddDevDeps(...deps: string[])- Add dev dependenciesaddPeerDeps(...deps: string[])- Add peer dependencies- Inherits all methods from Projen's
TypeScriptProject
PnpmWorkspace
Static Method:
PnpmWorkspace.of(project: Project): PnpmWorkspace | undefinedReturns the PnpmWorkspace component from a project if it exists.
TurboRepo
Static Method:
TurboRepo.of(project: Project): TurboRepo | undefinedReturns the TurboRepo component from a project if it exists.
Troubleshooting
"Cannot find module" errors
Run npx projen to regenerate configuration files.
Turbo Repo cache errors
- Ensure you've run the AWS login script
- If it's your first run of the day, try running the command twice
Build workflow failures
Check that you haven't manually edited generated files. If you have, run npx projen to restore them.
Dependency conflicts
Don't mix npm install with Projen. Always add dependencies through configuration.
Sub-project not appearing in workspace
- Ensure the sub-project has
parentset to the MonorepoProject - Ensure
outdiris set correctly - Run
npx projento regenerate the workspace file
Additional Resources
- Projen Documentation: https://projen.io
- Turbo Repo Docs: https://turbo.build/repo/docs
- PNPM Workspaces: https://pnpm.io/workspaces
- Code Drifters Configulator: https://www.npmjs.com/package/@codedrifters/packages
Remember: The goal is consistency and automation. Let the tools manage the boilerplate so you can focus on building features.
