Projen Project Management

This skill provides guidelines for working with projects managed by [projen](https://github.com/projen/projen), a powerful project configuration management tool that synthesizes and maintains project files.

Overview

Projen manages project configuration through a single source of truth (`.projenrc` file) and generates all necessary configuration files. This skill helps you work effectively with projen-managed projects by following the correct workflows and avoiding common pitfalls.

Task Execution

**Always use projen for task execution** instead of directly using npm, yarn, or other package managers.

Common Commands

Run tasks using the projen CLI:

```bash

node ./projen.js <task-name>

```

Essential Tasks

Discovering Available Tasks

Check `.projen/tasks.json` to see all available tasks, their descriptions, and execution steps.

File Modification Rules

Critical: Never Edit Generated Files

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

**Common generated files:**

Correct Modification Workflow

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

2. **Edit the .projenrc file**: Make your changes to the projen configuration

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

4. **Review changes**: Check that generated files reflect your configuration changes

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

Before Suggesting Changes

Always check if configuration files are managed by projen. If they are, suggest changes to `.projenrc` instead of direct file edits.

Dependency Management

Add Dependencies Through Projen

Never manually edit `package.json` or run `npm install` / `yarn add` directly.

Configuration Methods

In your `.projenrc` file, use projen's dependency methods:

After modifying dependencies in `.projenrc`, run `node ./projen.js` to update `package.json`.

Development Workflow

Standard Development Cycle

1. Make code or configuration changes

2. Run `node ./projen.js build` to verify everything works

3. Review and test your changes

4. Commit your work

Task Completion Criteria

A task is **not complete** until:

Working on Projen Itself

When contributing to the projen project itself:

Avoid Full Builds

Full builds take a long time. Run individual tasks instead.

Run Specific Tests

Target specific test files:

```bash

node ./projen.js test test/path-to-test.test.ts

```

Prefer running specific tests over the entire test suite during development.

Always Run the Linter

Use the linter frequently to ensure code quality:

```bash

node ./projen.js eslint

```

This ensures code is formatted correctly and follows best practices.

Best Practices

1. **Check tasks.json first**: Before asking how to do something, check `.projen/tasks.json` for available tasks

2. **Understand the workflow**: Configuration changes flow from `.projenrc` → `node ./projen.js` → generated files

3. **Commit generated files**: Always commit both configuration and generated files together

4. **Use projen for everything**: Task execution, dependency management, and configuration should all go through projen

5. **Read the markers**: Generated files clearly indicate they shouldn't be edited manually

Additional Resources

Common Mistakes to Avoid

❌ Editing `package.json` directly

✓ Edit `.projenrc` and run `node ./projen.js`

❌ Running `npm install package-name`

✓ Add to `.projenrc` with `addDeps()` and synthesize

❌ Modifying `tsconfig.json` manually

✓ Configure TypeScript options in `.projenrc`

❌ Forgetting to run `node ./projen.js` after configuration changes

✓ Always synthesize after modifying `.projenrc`

❌ Running full builds during active development

✓ Use targeted tasks like `compile` or specific tests