Projen Project Configuration

Expert guidance for working with [projen](https://github.com/projen/projen)-managed projects, including ClickUp-specific TypeScript and CDK project types.

Core Principles

When working in a projen-managed project, you MUST follow these rules:

1. Never Edit Generated Files Directly

**CRITICAL:** Files marked with comments like "~~ Generated by projen. To modify..." are automatically generated and will be overwritten.

2. Always Use Projen Tasks

Run tasks using `npx projen <task-name>` instead of npm/yarn/pnpm directly:

```bash

npx projen # Synthesize project configuration

npx projen build # Build project (includes tests)

npx projen test # Run tests only

npx projen compile # Compile source code only

```

Check `.projen/tasks.json` to see all available tasks with descriptions and steps.

3. Manage Dependencies Through Projen

Add dependencies via `.projenrc` configuration, not by editing `package.json`:

```typescript

// In .projenrc.ts

project.addDeps('my-dependency');

project.addDevDeps('my-dev-dependency');

project.addPeerDeps('my-peer-dependency');

```

Then run `npx projen` to update `package.json`.

Standard Workflow

1. Make changes to `.projenrc` configuration file

2. Run `npx projen` to synthesize and update generated files

3. Review the changes (check git diff)

4. Run `npx projen build` to verify everything compiles and tests pass

5. Commit both `.projenrc` and the generated files together

Task Completion Criteria

A task is not complete until:

ClickUp-Specific Projects

Project Types

This repository provides custom projen project types for ClickUp:

**TypeScript Libraries:**

**CDK Projects:**

Naming Conventions

Common Commands

```bash

Development

pnpm projen # Regenerate project files

pnpm build # Compile + test with coverage

pnpm test # Run tests

pnpm test:watch # Watch mode

pnpm eslint # Lint code

Test single file

pnpm test path/to/test-file.test.ts

Local testing before publish

pnpm build

Creates: dist/js/[email protected]

Use in another project:

projen new --from /path/to/dist/js/[email protected] <project-type>

```

Configuration Architecture

Key configuration modules:

- `renovate-workflow.ts` - Auto-merge dependency updates

- `cdk-diff-workflow.ts` - PR CDK diff visualization

- `codecov-bypass-workflow.ts` - Codecov requirement bypass

- `update-projen.ts` - Automated projen upgrades

- `datadog.ts` - Release event tracking

- `slack-alert.ts` - Release notifications

- `codecov.ts` - 90%+ coverage thresholds

Version Management

Centralized in `src/utils/parameters.ts`:

GitHub Actions

Generated projects include:

GitHub Packages Authentication

Configure access for consuming this library:

```bash

cat >> ~/.npmrc <<EOF

//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT

@time-loop:registry=https://npm.pkg.github.com/

EOF

```

PAT needs `read:packages` scope minimum.

Development Best Practices

Adding Features to Project Types

1. Create/modify module in `src/`

2. Add test in `test/` with snapshot testing

3. Export from `src/index.ts` if public API

4. Run `pnpm projen` to regenerate API.md

5. Run `pnpm test -- -u` to update snapshots

6. Verify with local tarball in test project

Snapshot Testing

When making changes:

1. Update code

2. Run `pnpm test` - snapshots may fail

3. **Carefully review** snapshot diffs

4. Run `pnpm test -- -u` to update snapshots if intentional

5. Commit updated snapshots with changes

Deep Merge Strategy

All project options use `ts-deepmerge` with layering:

1. Base defaults

2. User-provided options

3. Forced overrides

This ensures consistency while allowing customization.

Constraints and Limitations

Troubleshooting

**Problem:** Package.json changed after `pnpm projen`

**Solution:** Run `pnpm install` before committing

**Problem:** Generated files keep getting overwritten

**Solution:** Don't edit them directly - modify `.projenrc` instead

**Problem:** Snapshot tests failing

**Solution:** Review diffs, update with `pnpm test -- -u` if changes are intentional

Resources