Projen Project Management

Expert guidance for working with projen-managed projects, specifically focused on ClickUp's custom TypeScript and CDK project types.

What This Skill Does

This skill provides comprehensive knowledge for managing projects built with [projen](https://github.com/projen/projen), particularly those using ClickUp's custom project types from `clickup-projen`. It guides proper task execution, configuration management, dependency handling, and development workflows.

Step-by-Step Instructions

1. Identify Projen-Managed Files

**CRITICAL FIRST STEP:** Before editing ANY file in the project:

1. Check the top of the file for a comment like "~~ Generated by projen. To modify..."

2. If present, **NEVER edit this file directly**

3. Look for `.projenrc.ts`, `.projenrc.py`, or `.projenrc.json` in the project root

4. All configuration changes MUST go through the `.projenrc` file

**Files typically managed by projen:**

2. Check Available Tasks

Before running any build or test command:

```bash

View all available projen tasks

cat .projen/tasks.json

```

**Common tasks you'll find:**

3. Task Execution Pattern

**ALWAYS use projen for task execution**, not npm/yarn/pnpm directly:

```bash

✅ CORRECT

npx projen build

npx projen test

npx projen compile

❌ WRONG

npm run build

pnpm test

yarn compile

```

4. Making Configuration Changes

Follow this exact workflow:

1. **Edit `.projenrc` file** (e.g., `.projenrc.ts`)

```typescript

// Example: Adding a dependency

const project = new ClickUpTypeScriptProject({

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

// ... other config

});

project.addDeps('lodash');

project.addDevDeps('@types/lodash');

```

2. **Synthesize changes**

```bash

npx projen

```

3. **Review generated file changes**

```bash

git diff

```

4. **Commit BOTH `.projenrc` AND generated files**

```bash

git add .projenrc.ts package.json tsconfig.json

git commit -m "chore: add lodash dependency"

```

5. Adding Dependencies

**NEVER edit `package.json` directly.** Use `.projenrc` methods:

```typescript

// In .projenrc.ts

project.addDeps('dependency-name'); // Runtime dependency

project.addDevDeps('dev-dependency'); // Development dependency

project.addPeerDeps('peer-dependency'); // Peer dependency

project.addBundledDeps('bundled-dependency'); // Bundled dependency

```

After modifying `.projenrc.ts`:

```bash

npx projen

pnpm install # If package.json changed

```

6. Testing Workflow

When running tests:

```bash

Run all tests

npx projen test

Run tests in watch mode (if available)

npx projen test:watch

Test a single file

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

Update snapshots after intentional changes

pnpm test -- -u

```

**Task completion criteria** - A task is NOT complete until:

7. ClickUp Project-Specific Patterns

If working with `clickup-projen` project types:

**Package naming:**

**Version requirements:**

**Project types available:**

8. Local Development Testing

To test projen configuration changes locally:

```bash

Build the project

pnpm build

Creates: dist/js/[email protected]

In another project, create from local tarball:

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

```

9. Snapshot Testing

When modifying project types in `clickup-projen`:

1. Make code changes

2. Run `pnpm test` - snapshots will likely fail

3. **Carefully review snapshot diffs** to ensure changes are intentional

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

5. Commit updated snapshots with your changes

10. Common Workflows

**Adding a new feature to project types:**

1. Create/modify module in `src/`

2. Add test in `test/`

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

4. Run `pnpm projen` to regenerate docs

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

6. Test with local tarball

**Creating workflow integrations:**

1. Create module that exports configuration function

2. Accept project and optional config options

3. Use `project.github.addWorkflow()` or similar

4. Add helper functions for common patterns

5. Integrate into project constructors

Important Constraints

1. **Never manually edit generated files** - Always work through `.projenrc`

2. **Always use `npx projen <task>`** - Don't use npm/yarn/pnpm directly

3. **Check `.projen/tasks.json` first** - Know what tasks are available

4. **Commit both config and generated files** - They must stay in sync

5. **Run full build before considering task complete** - Tests must pass

6. **For ClickUp projects:** Follow naming conventions and version requirements

7. **JSII constraints apply** - When working on `clickup-projen` itself, TypeScript features are limited

Examples

**Example 1: Adding a dependency**

```typescript

// Edit .projenrc.ts

project.addDeps('axios');

// Then run:

npx projen

pnpm install

git add .projenrc.ts package.json pnpm-lock.yaml

git commit -m "chore: add axios dependency"

```

**Example 2: Running tests after code changes**

```bash

Make your code changes, then:

npx projen build # Full build with tests

Or incrementally:

npx projen compile # Check compilation

npx projen test # Run tests

npx projen eslint # Check linting

```

**Example 3: Creating a new ClickUp CDK construct library**

```bash

Use local tarball for testing

projen new --from /path/to/dist/js/[email protected] \

clickup-cdk-construct-library \

--name="@time-loop/cdk-my-construct"

```

Resources