Projen Project Management

Manage Projen-based TypeScript and AWS CDK projects using ClickUp's standardized project types from the `clickup-projen` library.

Overview

This skill helps you work with Projen-managed projects, particularly those using ClickUp's custom project types. Projen is a project configuration management tool that generates and maintains project files from a single `.projenrc` configuration.

Core Principles

Always Use Projen for Tasks

**Never** run npm/yarn/pnpm commands directly. Always use projen tasks:

```bash

npx projen <task-name>

```

Check available tasks in `.projen/tasks.json` for descriptions and steps.

Never Manually Edit Generated Files

Files with comments like "~~ Generated by projen. To modify..." must **never** be edited directly. Instead:

1. Modify `.projenrc.ts` (or `.projenrc.py`, `.projenrc.json`)

2. Run `npx projen` to regenerate files

3. Review and commit changes

Standard Workflow

1. Make changes to `.projenrc` configuration

2. Run `npx projen` to synthesize

3. Run `pnpm install` if package.json changed

4. Review generated file changes

5. Commit both `.projenrc` and generated files

Common Tasks

Development Commands

```bash

Regenerate all project files

pnpm projen

Full build (compile + test + coverage)

pnpm build

Run tests

pnpm test

Run tests in watch mode

pnpm test:watch

Test single file

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

Compile only

pnpm compile

Lint code

pnpm eslint

```

Task Completion Criteria

A task is complete only when:

ClickUp Projen Architecture

Project Types

**`ClickUpTypeScriptProject`** - Base TypeScript library

**`ClickUpCdkConstructLibrary`** - Reusable CDK constructs

**`ClickUpCdkTypeScriptApp`** - CDK applications

Configuration Strategy

Uses deep merge pattern: defaults → project options → forced overrides

```typescript

// Example .projenrc.ts

const project = new ClickUpCdkConstructLibrary({

name: 'cdk-my-construct',

cdkVersion: '2.189.0',

// Options deep-merged with opinionated defaults

});

project.synth();

```

Managing Dependencies

Add dependencies through projen configuration, **not** package.json:

```typescript

// In .projenrc.ts

project.addDeps('aws-cdk-lib');

project.addDevDeps('aws-cdk');

project.addPeerDeps('constructs');

```

Then run `npx projen` to update package.json and `pnpm install`.

Testing Changes Locally

Build a local tarball to test in another project:

```bash

pnpm build

Creates: dist/js/[email protected]

In another project:

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

```

Snapshot Testing

Tests use Jest snapshots extensively:

```bash

Run tests (may fail if snapshots outdated)

pnpm test

Review snapshot diffs carefully

Update snapshots if changes are intentional

pnpm test -- -u

Commit updated snapshots with your changes

```

GitHub Packages Authentication

Consumers need GitHub PAT configured:

```bash

cat >> ~/.npmrc <<EOF

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

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

EOF

```

PAT requires `read:packages` scope.

Project Structure

```

.

├── .projenrc.ts # Project configuration (edit this)

├── .projen/

│ └── tasks.json # Available tasks

├── src/ # Source TypeScript files

├── test/ # Jest tests with snapshots

├── dist/ # Built JSII artifacts (generated)

└── lib/ # Compiled TypeScript (generated)

```

Automated Workflows

Generated projects include:

Adding Features

When extending project types:

1. Create/modify module in `src/`

2. Add corresponding test in `test/`

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

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

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

6. Verify with local tarball test

Version Management

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

Update once to cascade to all consumers.

Naming Conventions

Important Notes

Resources