@codedrifters/configulator 0.0.52 → 0.0.54

package/README.md

@@ -1,4 +1,344 @@
-# Configulator
+# Project Setup Guide: Projen & Configulator
+
+## 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, 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 Code Drifters' 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
+
+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
+
+## Creating a New Project
+
+### Basic Setup
+
+```bash
+npx projen new --from @codedrifters/Configulator@0.48 monorepo
+```
+
+This creates a project with:
+
+- TypeScript configuration
+- Prettier for code formatting
+- VS Code settings
+- GitHub workflows (build, PR checks)
+- Weekly dependency upgrade workflow
+
+### Minimal Configuration Example
+
+The simplest `.projenrc.ts` file:
+
+```typescript
+import { MonorepoProject } from '@codedrifters/Configulator';
+
+const project = new MonorepoProject({
+  name: 'my-project-name'
+});
+
+project.synth();
+```
+
+## Important: 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:**
+```bash
+npm install some-package
+```
+
+**CORRECT:** Add dependencies in your `.projenrc.ts` configuration and run `npx projen`.
+
+## Understanding the Monorepo Configuration
+
+Our monorepo projects are configured in `.projenrc/` folder with multiple files:
+
+```
+.projenrc/
+├── index.ts          # Main configuration
+├── root.ts           # Root project config
+├── sample-app.ts     # Example sub-project
+└── ehr-project.ts    # Actual sub-project
+```
+
+### Key Configuration Options
+
+The root configuration extends Projen's TypeScript app with our defaults:
+
+- **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
+
+## 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
+
+### Running Locally
+
+Before using Turbo Repo locally, you need AWS credentials:
+
+```bash
+# Run the login script (credentials last ~8 hours)
+./scripts/aws-profile-turbo-repo.sh
+```
+
+**Common 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
+
+## 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
+
+**Review Process:** If tests pass, the updates are likely safe to merge. Good test coverage makes this workflow reliable.
+
+## VS Code Configuration
+
+Projects automatically include VS Code settings:
+
+- Tab size: 2 spaces
+- Format on save with Prettier
+- Recommended extensions (can be customized)
+
+Settings are in `.vscode/settings.json` (auto-generated).
+
+## Custom Components
+
+You can create custom components for repeated configurations. Examples:
+
+### Storybook Component
+
+```typescript
+// Adds Storybook with all necessary config
+import { StorybookComponent } from './.projenrc/storybook';
+
+// In your project config
+new StorybookComponent(project);
+```
+
+### Playwright Component
+
+```typescript
+// Adds Playwright testing framework
+import { PlaywrightComponent } from './.projenrc/playwright';
+
+new PlaywrightComponent(project);
+```
+
+Components encapsulate:
+
+- Dependencies (dev and production)
+- Configuration files
+- 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.
+
+## Working with Monorepos
+
+### Workspace Structure
+
+Our monorepos use PNPM workspaces. The workspace file (`.pnpm-workspace.yaml`) is auto-generated and lists all sub-projects:
+
+```yaml
+packages:
+  - 'packages/package-a'
+  - 'packages/package-b'
+  - 'apps/frontend'
+```
+
+### Opening Sub-Projects in VS Code
+
+You can:
+
+- Open the entire monorepo (uses root `.vscode/`)
+- Open individual sub-projects (can have their own `.vscode/`)
+
+For individual projects, consider creating VS Code workspace files (advanced topic).
+
+## Workflow Tips
+
+### Before Committing
+
+Run Turbo build locally to cache everything:
+
+```bash
+# This caches outputs that GitHub Actions can reuse
+turbo run build
+```
+
+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
+
+### Updating Configulator
+
+To receive updates from Configulator in your project:
+
+1. Update the version in `versions.ts`
+2. Run `npx projen`
+3. Review and test changes
+4. Commit
+
+## Common Patterns
+
+### Version Management
+
+Versions for specific packages can be pinned in a `versions.ts` file:
+
+```typescript
+export const versions = {
+  turbo: '1.10.0',
+  pnpm: '8.6.0',
+  node: '18.x'
+};
+```
+
+This gives you explicit control over important dependencies while letting others auto-update.
+
+### AWS Profiles Setup
+
+For Turbo Repo caching and CDK deployment, set up AWS profiles:
+
+```bash
+# Run the appropriate setup script
+./scripts/aws-profile-turbo-repo.sh
+```
+
+These create temporary credentials (~8 hours) using SSO - much safer than long-lived access keys.
+
+## 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.
+
+## Next Steps
+
+- 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
+
+## 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
+
+---
+
+**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.
 
@@ -12,4 +352,4 @@ 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.
+These docs are a work in progress and very light currently.

package/package.json

@@ -13,7 +13,7 @@
     "@swc/core": "^1.13.20",
     "@swc/jest": "^0.2.39",
     "@types/jest": "^30.0.0",
-    "@types/node": "^22.18.10",
+    "@types/node": "^22.18.11",
     "@typescript-eslint/eslint-plugin": "^8",
     "@typescript-eslint/parser": "^8",
     "commit-and-tag-version": "^12",
@@ -35,12 +35,12 @@
     "projen": "0.98.0"
   },
   "dependencies": {
-    "@jsii/spec": "^1.115.0",
+    "@jsii/spec": "^1.116.0",
     "type-fest": "^4"
   },
   "main": "lib/index.js",
   "license": "MIT",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "types": "lib/index.d.ts",
   "//": "~~ Generated by projen. To modify, edit .projenrc.ts and run \"npx projen\".",
   "scripts": {