Projen ClickUp Project Management

Expert assistant for working with projen-managed projects using ClickUp's custom project types (`clickup-projen`). Ensures proper task execution, configuration management, and adherence to project conventions.

Core Principles

1. Task Execution via Projen

**ALWAYS use projen for task execution** instead of direct package manager commands:

```bash

npx projen # Synthesize project configuration

npx projen build # Full build with tests

npx projen test # Run tests only

npx projen compile # Compile TypeScript only

```

**Before running any task:**

2. Configuration Management

**NEVER manually edit generated files.** Files marked with "~~ Generated by projen. To modify..." are synthesized from `.projenrc`.

**Correct workflow for changes:**

1. Check if file is projen-managed (look for generation comment)

2. If managed, edit `.projenrc.ts` (or `.projenrc.py`/`.projenrc.json`)

3. Run `npx projen` to regenerate files

4. Review changes

5. Commit both `.projenrc` AND generated files

**Common generated files:**

3. Dependency Management

**Add dependencies through projen configuration**, not package manager commands:

```typescript

// In .projenrc.ts

project.addDeps('lodash'); // Runtime dependency

project.addDevDeps('jest'); // Dev dependency

project.addPeerDeps('react'); // Peer dependency

```

After modifying dependencies:

```bash

npx projen # Regenerate package.json

pnpm install # Install new dependencies

```

ClickUp Project Types

ClickUpTypeScriptProject

Base TypeScript library project with ClickUp conventions.

**Key features:**

ClickUpCdkConstructLibrary

For reusable CDK construct libraries.

**Naming convention:** Use `cdk-*` prefix (e.g., `cdk-my-library`)

**Pre-configured with:**

ClickUpCdkTypeScriptApp

For CDK applications.

**Naming convention:** Use `*-cdk` suffix (e.g., `my-app-cdk`)

**Pre-configured with:**

Development Workflows

Standard Development Cycle

```bash

1. Make changes to source code

2. Run full build

npx projen build

3. Verify completion criteria:

✓ All tests pass

✓ No compilation errors

✓ No linting errors

✓ Full build succeeds

```

**Task is NOT complete until all criteria pass.**

Testing Workflows

```bash

Run all tests

npx projen test

Run tests in watch mode

pnpm test:watch

Run single test file

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

Update snapshots (after reviewing changes)

pnpm test -- -u

```

Local Development Testing

Test projen configuration changes locally before publishing:

```bash

1. Build local tarball

pnpm build

2. Use in another project

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

```

Adding New Features to Project Types

When modifying `clickup-projen` itself:

1. Create/modify module in `src/`

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

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

4. Regenerate: `npx projen`

5. Update snapshots: `pnpm test -- -u`

6. Verify with local tarball in test project

Common Tasks

Modifying Project Configuration

**Wrong:**

```bash

❌ DON'T manually edit package.json

vim package.json

```

**Right:**

```typescript

// ✅ Edit .projenrc.ts

const project = new ClickUpTypeScriptProject({

name: '@time-loop/my-project',

deps: ['lodash'], // Add dependency here

});

```

Then:

```bash

npx projen # Regenerate

pnpm install # Install dependencies

```

Updating Dependencies

**Wrong:**

```bash

❌ DON'T use pnpm add directly

pnpm add lodash

```

**Right:**

```typescript

// ✅ In .projenrc.ts

project.addDeps('lodash');

```

```bash

npx projen

pnpm install

```

GitHub Actions Configuration

Workflows are generated automatically. To customize:

```typescript

// In .projenrc.ts

const project = new ClickUpCdkTypeScriptApp({

cdkDiffOptions: {

enableAutoDiff: true, // Add CDK diff workflow

},

});

```

Common generated workflows:

Authentication & Setup

GitHub Packages Access

Consumers need GitHub Packages authentication:

```bash

cat >> ~/.npmrc <<EOF

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

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

EOF

```

**Required PAT scope:** `read:packages` (minimum)

Repository Secrets

Ensure these secrets are configured:

Naming Conventions

All packages use `@time-loop/` scope (enforced by `normalizeName()`):

| Project Type | Convention | Example |

|-------------|-----------|---------|

| CDK Construct Library | `cdk-*` prefix | `@time-loop/cdk-my-library` |

| CDK Application | `*-cdk` suffix | `@time-loop/my-app-cdk` |

| TypeScript Library | No specific convention | `@time-loop/my-library` |

Version Constraints

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

Troubleshooting

"File is managed by projen" Error

**Solution:** Don't edit the file directly. Edit `.projenrc.ts` and run `npx projen`.

Package.json Changes Not Taking Effect

**Solution:**

```bash

npx projen # Regenerate first

pnpm install # Then install

```

Tests Failing After Changes

**If snapshot tests fail:**

1. Review snapshot diffs carefully

2. If changes are intentional: `pnpm test -- -u`

3. Commit updated snapshots with your changes

Build Failures

**Task completion checklist:**

```bash

npx projen compile # Must pass

npx projen test # Must pass

npx projen eslint # Must pass (or included in build)

npx projen build # Must pass

```

Resources

Important Reminders

1. **Always use `npx projen <task>`** - Never run package manager tasks directly

2. **Check `.projen/tasks.json`** - Before running any task

3. **Never edit generated files** - Always modify `.projenrc.ts` instead

4. **Task not complete until all checks pass** - Build, test, lint must all succeed

5. **Commit both config and generated files** - Both `.projenrc.ts` and its outputs