Projen Project Management

This skill provides expert guidance for working with projen-managed projects. Projen is a project configuration management tool that generates and manages project files through code.

Core Principles

1. Always Use Projen for Task Execution

Never use npm, yarn, or other package managers directly. All tasks should be run through projen:

```bash

Synthesize project configuration files

node ./projen.js

Build the project (includes tests)

node ./projen.js build

Run tests only

node ./projen.js test

Compile source code only

node ./projen.js compile

```

2. Check Available Tasks

Before running any task, check `.projen/tasks.json` to see all available tasks, their descriptions, and steps. This file is the source of truth for what tasks are available in the project.

3. Never Manually Edit Generated Files

Files marked with comments like "~~ Generated by projen. To modify..." must NEVER be edited directly. These files include:

Making Configuration Changes

Step-by-Step Workflow

1. **Identify the configuration file**: Look for `.projenrc.ts`, `.projenrc.py`, `.projenrc.json`, or similar at the project root

2. **Make your changes**: Edit the `.projenrc` file to modify project configuration

3. **Synthesize**: Run `node ./projen.js` to regenerate all project files

4. **Review**: Check the changes to generated files

5. **Commit**: Commit both the `.projenrc` file and all generated files together

Adding Dependencies

Never edit `package.json` or run `npm install` directly. Instead:

```typescript

// In .projenrc.ts

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

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

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

```

Then run `node ./projen.js` to update `package.json` and lock files.

Development Best Practices

Task Completion Criteria

A task is NOT complete until ALL of the following pass:

1. `node ./projen.js compile` - No compilation errors

2. `node ./projen.js test` - All tests pass

3. Linting passes (usually part of build)

4. `node ./projen.js build` - Full build succeeds

For Projen Development Itself

When working on the projen project itself:

Common Scenarios

Scenario: User wants to add a new script

**Wrong approach**: Edit `package.json` directly

**Correct approach**:

1. Open `.projenrc` file

2. Add script configuration (e.g., `project.addTask('script-name', { ... })`)

3. Run `node ./projen.js`

4. Verify the script appears in generated files

Scenario: User wants to change TypeScript configuration

**Wrong approach**: Edit `tsconfig.json`

**Correct approach**:

1. Open `.projenrc` file

2. Modify TypeScript configuration options

3. Run `node ./projen.js`

4. Review changes to `tsconfig.json`

Scenario: User wants to add a GitHub Action

**Wrong approach**: Create or edit workflow files in `.github/workflows/`

**Correct approach**:

1. Open `.projenrc` file

2. Configure GitHub workflows using projen's API

3. Run `node ./projen.js`

4. Review generated workflow files

Important Reminders

Resources