@codedrifters/configulator 0.0.75 → 0.0.77

package/README.md

@@ -1,4 +1,24 @@
-# Project Setup Guide: Projen & Configulator
+# Configulator
+
+A library of [Projen](https://projen.io/) 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](#overview)
+- [What is Projen?](#what-is-projen)
+- [What is Configulator?](#what-is-configulator)
+- [Project Types](#project-types)
+  - [MonorepoProject](#monorepoproject)
+  - [TypeScriptProject](#typescriptproject)
+- [Usage Patterns](#usage-patterns)
+- [Configuration Options](#configuration-options)
+- [Turbo Repo](#turbo-repo)
+- [PNPM Workspace](#pnpm-workspace)
+- [File Management Rules](#file-management-rules)
+- [Workflow Tips](#workflow-tips)
+- [API Reference](#api-reference)
+- [Troubleshooting](#troubleshooting)
+- [Additional Resources](#additional-resources)
 
 ## Overview
 
@@ -23,11 +43,10 @@ Projen is a project generator and configuration management tool that:
 
 ## What is Configulator?
 
-configulator is Code Drifters' custom extension of Projen. It:
+Configulator is CodeDrifters' custom extension of Projen. It:
 
 - Extends standard Projen configurations with our preferred defaults
 - Provides company-specific components and workflows
-- Currently at version 0.48 (alpha/internal use)
 - Available as an npm package: `@codedrifters/configulator`
 
 ### Why We Built It
@@ -39,84 +58,454 @@ Instead of setting up each new project from scratch (90% identical setup repeate
 - Maintain standardized tooling across all projects
 - Receive updates to common configurations automatically
 
-## Creating a New Project
+## Project Types
 
-### Basic Setup
+Configulator provides two main project types designed for monorepo workflows:
 
-```bash
-npx projen new --from @codedrifters/Configulator@0.48 monorepo
-```
+### 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
 
-This creates a project with:
+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
 
-- TypeScript configuration
-- Prettier for code formatting
-- VS Code settings
-- GitHub workflows (build, PR checks)
-- Weekly dependency upgrade workflow
+#### Key Features
 
-### Minimal Configuration Example
+- **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
 
-The simplest `.projenrc.ts` file:
+#### Basic Example
 
 ```typescript
-import { MonorepoProject } from '@codedrifters/Configulator';
+import { MonorepoProject } from '@codedrifters/configulator';
 
 const project = new MonorepoProject({
-  name: 'my-project-name'
+  name: 'my-monorepo'
 });
 
 project.synth();
 ```
 
-## Important: File Management Rules
+#### Advanced Example with Remote Cache
 
-### DO NOT Edit These Files Directly
+```typescript
+import { MonorepoProject } from '@codedrifters/configulator';
 
-Projen manages many files automatically. Never edit these files by hand:
+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'],
+    },
+  },
+});
 
-- Configuration files (`.prettierrc`, `tsconfig.json`, etc.)
-- GitHub workflows (`.github/workflows/*`)
-- Build scripts
-- Most files listed in `.projen/files.json`
+project.synth();
+```
 
-### Exception: package.json
+#### Configuration Options
 
-`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.
+The `MonorepoProject` accepts all options from `TypeScriptProjectOptions` plus:
 
-### Adding Dependencies
+| 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 |
 
-**WRONG:**
-```bash
-npm install some-package
+**Default Behavior:**
+- `projenrcTs: true` - Uses TypeScript for projen configuration
+- `prettier: true` - Enables Prettier formatting
+- `licensed: false` - No license by default
+- `sampleCode: false` - No sample code generated
+- `jest: false` - Jest disabled at root level
+- `release: false` - Root project is not released
+- `depsUpgrade: false` - No automatic dependency upgrades at root
+- `disableTsconfigDev: true` - No tsconfig.dev.json at root
+- `packageManager: NodePackageManager.PNPM` - PNPM is mandatory
+- `defaultReleaseBranch: "main"` - Standard branch name
+
+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 `MonorepoProject` when used as a sub-project
+- **SWC for Testing**: Uses `@swc/jest` instead of `ts-jest` for faster test execution
+- **Prettier Integration**: Automatic Prettier configuration
+- **Jest Configuration**: External Jest config file (not in package.json) with sensible defaults
+- **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
+
+```typescript
+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();
 ```
 
-**CORRECT:** Add dependencies in your `.projenrc.ts` configuration and run `npx projen`.
+#### Example with Release Configuration
 
-## Understanding the Monorepo Configuration
+```typescript
+import { MonorepoProject, TypeScriptProject } from '@codedrifters/configulator';
 
-Our monorepo projects are configured in `.projenrc/` folder with multiple files:
+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();
 ```
-.projenrc/
-├── index.ts          # Main configuration
-├── root.ts           # Root project config
-├── sample-app.ts     # Example sub-project
-└── ehr-project.ts    # Actual sub-project
+
+#### Parent-Child Relationship
+
+When `TypeScriptProject` is created with a `parent` that is a `MonorepoProject`:
+
+1. **PNPM Version**: Automatically inherits the PNPM version from the parent
+2. **Workspace Integration**: Automatically added to the parent's PNPM workspace
+3. **Turborepo Integration**: If parent has Turborepo enabled, the sub-project automatically gets Turborepo task configuration
+4. **Catalog Dependencies**: Can reference catalog dependencies defined in the parent's workspace
+5. **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) |
+
+**Jest Configuration:**
+- Uses external `jest.config.json` file
+- Configured to use `@swc/jest` for faster compilation
+- Test files in `src/` directory
+- ESLint rule `import/no-extraneous-dependencies` disabled for test files
+
+**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:
+
+1. **Create the root project** using `MonorepoProject`:
+
+```typescript
+// 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;
+};
+```
+
+2. **Add sub-projects** using `TypeScriptProject`:
+
+```typescript
+// 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 };
+};
+```
+
+3. **Wire everything together** in your main projenrc file:
+
+```typescript
+// .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:
+
+```typescript
+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();
 ```
 
-### Key Configuration Options
+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.ts` or `projenrc/*.ts`), never by manually running package manager commands like `npm install`, `pnpm add`, or `yarn add`. Manual installation will create conflicts with Projen-managed files and may be overwritten when you run `npx projen`.
+
+#### Using Catalog Dependencies
+
+The `MonorepoProject` automatically sets up a default catalog with common dependencies:
+
+```typescript
+// 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:
+
+```typescript
+const myPackage = new TypeScriptProject({
+  // ... other options
+  devDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
+  peerDeps: ['aws-cdk-lib@catalog:', 'constructs@catalog:'],
+});
+```
 
-The root configuration extends Projen's TypeScript app with our defaults:
+#### Workspace Dependencies
 
-- **TypeScript:** Enabled by default
-- **Prettier:** Enabled for consistent formatting
-- **License:** Unlicensed (for client work)
-- **Package Manager:** PNPM (mandatory)
-- **Default Branch:** main
-- **Sample Code:** Disabled (no hello-world examples)
-- **Dependency Upgrades:** Configured but can be adjusted
-- **Turbo Repo:** Enabled for monorepo builds
+Sub-projects can depend on other packages in the same monorepo:
+
+```typescript
+const packageB = new TypeScriptProject({
+  // ... other options
+  deps: ['@myorg/package-a@workspace:*'],
+});
+```
+
+#### Custom Catalog
+
+You can also define custom catalogs in the `MonorepoProject`:
+
+```typescript
+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:
+
+```typescript
+// Default catalog
+deps: ['react@catalog:react']
+
+// Named catalog
+deps: ['react@catalog:frontend/react']
+```
+
+### 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](#turbo-repo) section for more details.
+
+## Configuration Options
+
+### MonorepoProjectOptions
+
+Extends `TypeScriptProjectOptions` with:
+
+```typescript
+interface MonorepoProjectOptions {
+  name: string; // Required
+  turbo?: boolean; // Default: true
+  turboOptions?: TurboRepoOptions;
+  pnpmOptions?: {
+    version?: string;
+    pnpmWorkspaceOptions?: PnpmWorkspaceOptions;
+  };
+  // ... all TypeScriptProjectOptions
+}
+```
+
+### TypeScriptProjectOptions
+
+Extends Projen's `TypeScriptProjectOptions` with CodeDrifters defaults. See the [TypeScriptProject](#typescriptproject) section for details.
+
+### TurboRepoOptions
+
+```typescript
+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
+
+```typescript
+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
 
@@ -139,6 +528,25 @@ Turbo Repo is a build system for monorepos that:
 
 **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`:
+
+```typescript
+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:
@@ -156,150 +564,170 @@ Before using Turbo Repo locally, you need AWS credentials:
 - **Selective Rebuilds:** Only changed code rebuilds, not the entire monorepo
 - **Local + CI Sharing:** Cache between your machine and GitHub Actions
 
-## Automatic Dependency Updates
-
-Our projects include a GitHub Action that:
-
-- Runs weekly (configurable)
-- Checks for updated packages
-- Opens a PR with updates
-- Runs all tests automatically
+## PNPM Workspace
 
-**Review Process:** If tests pass, the updates are likely safe to merge. Good test coverage makes this workflow reliable.
+The `MonorepoProject` automatically generates and manages `pnpm-workspace.yaml`. This file:
 
-## VS Code Configuration
+- Lists all sub-projects in the `packages` array
+- Configures PNPM settings like `minimumReleaseAge` and `onlyBuiltDependencies`
+- Defines dependency catalogs for version management
 
-Projects automatically include VS Code settings:
+### Workspace Structure
 
-- Tab size: 2 spaces
-- Format on save with Prettier
-- Recommended extensions (can be customized)
+The workspace file is auto-generated and lists all sub-projects:
 
-Settings are in `.vscode/settings.json` (auto-generated).
+```yaml
+packages:
+  - 'packages/package-a'
+  - 'packages/package-b'
+  - 'apps/frontend'
+```
 
-## Custom Components
+Sub-projects are automatically discovered from `project.subprojects` and any additional paths specified in `pnpmWorkspaceOptions.subprojects`.
 
-You can create custom components for repeated configurations. Examples:
+### Configuration
 
-### Storybook Component
+Configure the workspace through `pnpmOptions.pnpmWorkspaceOptions`:
 
 ```typescript
-// Adds Storybook with all necessary config
-import { StorybookComponent } from './.projenrc/storybook';
-
-// In your project config
-new StorybookComponent(project);
+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',
+      },
+    },
+  },
+});
 ```
 
-### Playwright Component
-
-```typescript
-// Adds Playwright testing framework
-import { PlaywrightComponent } from './.projenrc/playwright';
+## File Management Rules
 
-new PlaywrightComponent(project);
-```
+### DO NOT Edit These Files Directly
 
-Components encapsulate:
+Projen manages many files automatically. Never edit these files by hand:
 
-- Dependencies (dev and production)
-- Configuration files
+- Configuration files (`.prettierrc`, `tsconfig.json`, etc.)
+- GitHub workflows (`.github/workflows/*`)
 - Build scripts
-- Sample files (one-time generation)
-
-### Sample Files vs Config Files
-
-**Config Files:** Deleted and regenerated on every `npx projen` run
-
-- YAML, JSON, INI files
-- TypeScript configs
-- Build configurations
-
-**Sample Files:** Generated once, never overwritten
-
-- Starter code templates
-- Example tests
-- Framework setup files (e.g., Storybook's `main.ts`)
-
-Sample files give you a starting point but won't receive updates. Modify them freely for your needs.
+- Most files listed in `.projen/files.json`
 
-## Working with Monorepos
+### Exception: package.json
 
-### Workspace Structure
+`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.
 
-Our monorepos use PNPM workspaces. The workspace file (`.pnpm-workspace.yaml`) is auto-generated and lists all sub-projects:
+### Adding Dependencies
 
-```yaml
-packages:
-  - 'packages/package-a'
-  - 'packages/package-b'
-  - 'apps/frontend'
+**WRONG:**
+```bash
+npm install some-package
 ```
 
-### Opening Sub-Projects in VS Code
-
-You can:
-
-- Open the entire monorepo (uses root `.vscode/`)
-- Open individual sub-projects (can have their own `.vscode/`)
+**CORRECT:** Add dependencies in your `.projenrc.ts` configuration and run `npx projen`.
 
-For individual projects, consider creating VS Code workspace files (advanced topic).
+```typescript
+const project = new TypeScriptProject({
+  // ... other options
+  deps: ['some-package'],
+});
+```
 
 ## Workflow Tips
 
 ### Before Committing
 
-Run Turbo build locally to cache everything:
+Run Turbo build locally (from monorepo root) to cache everything:
 
 ```bash
 # This caches outputs that GitHub Actions can reuse
-turbo run build
+pnpm build:all
 ```
 
 Then commit and push. Your GitHub build will be much faster.
 
 ### Adding New Packages
 
-1. Edit your `.projenrc.ts` configuration
-2. Add dependencies using the project API
-3. Run `npx projen` to regenerate configs
-4. Commit the changes
+1. Create a new configuration file in `projenrc/` (e.g., `projenrc/new-package.ts`)
+2. Export a function that creates a `TypeScriptProject` with the parent as a parameter
+3. Import and call it in your main projenrc file
+4. Run `npx projen` to regenerate configs
+5. Commit the changes
+
+Example:
+
+```typescript
+// 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:
 
-1. Update the version in `versions.ts`
+1. Update the version in your projenrc definition file
 2. Run `npx projen`
 3. Review and test changes
 4. Commit
 
-## Common Patterns
+## API Reference
 
-### Version Management
+### MonorepoProject
+
+**Constructor:**
+```typescript
+new MonorepoProject(options: MonorepoProjectOptions)
+```
 
-Versions for specific packages can be pinned in a `versions.ts` file:
+**Key Properties:**
+- `pnpmVersion: string` - The PNPM version used by the monorepo
 
+**Key Methods:**
+- Inherits all methods from `TypeScriptAppProject`
+
+### TypeScriptProject
+
+**Constructor:**
 ```typescript
-export const versions = {
-  turbo: '1.10.0',
-  pnpm: '8.6.0',
-  node: '18.x'
-};
+new TypeScriptProject(options: TypeScriptProjectOptions)
 ```
 
-This gives you explicit control over important dependencies while letting others auto-update.
+**Key Methods:**
+- `addDeps(...deps: string[])` - Add runtime dependencies
+- `addDevDeps(...deps: string[])` - Add dev dependencies
+- `addPeerDeps(...deps: string[])` - Add peer dependencies
+- Inherits all methods from Projen's `TypeScriptProject`
 
-### AWS Profiles Setup
+### PnpmWorkspace
 
-For Turbo Repo caching and CDK deployment, set up AWS profiles:
+**Static Method:**
+```typescript
+PnpmWorkspace.of(project: Project): PnpmWorkspace | undefined
+```
 
-```bash
-# Run the appropriate setup script
-./scripts/aws-profile-turbo-repo.sh
+Returns the PnpmWorkspace component from a project if it exists.
+
+### TurboRepo
+
+**Static Method:**
+```typescript
+TurboRepo.of(project: Project): TurboRepo | undefined
 ```
 
-These create temporary credentials (~8 hours) using SSO - much safer than long-lived access keys.
+Returns the TurboRepo component from a project if it exists.
 
 ## Troubleshooting
 
@@ -320,36 +748,19 @@ Check that you haven't manually edited generated files. If you have, run `npx pr
 
 Don't mix `npm install` with Projen. Always add dependencies through configuration.
 
-## Next Steps
+**Sub-project not appearing in workspace**
 
-- Learn about CDK setup for AWS deployments
-- Explore creating custom components for your team's needs
-- Review project-specific configurations in existing repos (on-site, openhigh)
-- Set up AWS profiles for Turbo Repo remote caching
+- Ensure the sub-project has `parent` set to the MonorepoProject
+- Ensure `outdir` is set correctly
+- Run `npx projen` to regenerate the workspace file
 
 ## Additional Resources
 
 - **Projen Documentation:** https://projen.io
 - **Turbo Repo Docs:** https://turbo.build/repo/docs
-- **Code Drifters Configulator:** https://www.npmjs.com/package/@codedrifters/configulator
+- **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.
-
-# **ARCHIVE FROM INITIAL SETUP**
-## Configulator
-
-A library of [Projen](https://projen.io/) components used by CodeDrifters to manage repository configuration across various projects.
-
-## Usage
-
-To init a monorepo you can use:
-
-`npx projen new --from @codedrifters/configulator monorepo`
-
-For a specific version, use:
-
-`npx projen new --from @codedrifters/configulator@0.0.15 monorepo`
-
-These docs are a work in progress and very light currently.