Skip to content

Commit 911ba87

Browse files
patricktreepatricktree
committed
chore: create CLAUDE.md files
1 parent a05bfdc commit 911ba87

File tree

5 files changed

+208
-40
lines changed

5 files changed

+208
-40
lines changed

‎CLAUDE.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# CLAUDE.md - Repository Context
2+
3+
This document provides essential information about the `packages-private` repository to help AI assistants understand the codebase structure, conventions, and development practices.
4+
5+
## Repository Overview
6+
7+
This is a **TypeScript monorepo** managed with **pnpm workspaces** and **Turbo**. It contains various utility packages, tools, and libraries created by Patrick Kerschbaum (@pkerschbaum).
8+
9+
### Key Technologies
10+
11+
- **Language**: TypeScript
12+
- **Package Manager**: pnpm
13+
- **Build System**: Turbo (via custom `superturbo` wrapper)
14+
- **Node Version**: Specified in `.nvmrc`
15+
- **Module Systems**: Both CommonJS and ESM packages
16+
17+
### Repository Structure
18+
19+
```txt
20+
packages-private/
21+
├── packages/ # Main packages (published to npm)
22+
├── platform/ # Internal platform utilities
23+
│ ├── config-eslint/
24+
│ ├── config-typescript/
25+
│ └── superturbo/
26+
├── test/ # Test packages
27+
├── patches/ # pnpm patches for dependencies
28+
└── turbo.json # Turbo configuration
29+
```
30+
31+
## Development Setup
32+
33+
### Prerequisites
34+
35+
1. Install Node.js using nvm: `nvm install`
36+
2. Enable pnpm via corepack: `corepack enable`
37+
3. Install native toolchain for Node.js modules: Run the installation instructions "A C/C++ compiler tool chain for your platform" of [microsoft/vscode/wiki/How-to-Contribute#prerequisites](https://github.com/microsoft/vscode/wiki/How-to-Contribute#prerequisites)
38+
39+
### Common Commands
40+
41+
```bash
42+
pnpm install # Install all dependencies
43+
pnpm run build # Build all packages
44+
pnpm run lint # Run ESLint across all packages
45+
pnpm run lint:fix # Fix linting issues
46+
pnpm run format # Format with Prettier
47+
pnpm run nuke # Clean all build artifacts and node_modules
48+
```
49+
50+
## Coding Conventions
51+
52+
### TypeScript Configuration
53+
54+
- **Base config**: `platform/config-typescript/tsconfig.json`
55+
- **Strict mode**: Enabled with additional strict checks
56+
- **Module resolution**: Node16
57+
- **Path aliases**: Use `#pkg/*` for internal imports (transformed to relative paths during build)
58+
- **Custom transformer**: `typescript-transform-paths` for path alias support
59+
60+
### Code Style
61+
62+
- **Formatting**: Prettier with single quotes, trailing commas, 100-char line width
63+
- **Linting**: ESLint with TypeScript support, all errors shown as warnings
64+
- **Import ordering**: External → workspace → internal, alphabetically sorted
65+
- **No default exports**: Use named exports only
66+
- **No relative imports**: Use `#pkg/*` aliases instead (except for assets)
67+
68+
### Package Structure
69+
70+
Each package typically follows this structure:
71+
72+
```txt
73+
package-name/
74+
├── src/ # Source files
75+
├── dist/ # Build output (gitignored)
76+
├── package.json # Package manifest
77+
├── tsconfig.project.json # TypeScript config
78+
└── turbo.json # Turbo config (if needed)
79+
```
80+
81+
### Package Configuration
82+
83+
- **Exports**: Use `exports` field in package.json
84+
- **Types**: TypeScript declarations generated with source maps
85+
- **Scripts**:
86+
- `build`: Compile TypeScript
87+
- `dev`: Watch mode compilation
88+
- `lint`: Run ESLint
89+
- `nuke`: Clean artifacts
90+
91+
## Important Patterns
92+
93+
### Path Aliases
94+
95+
All internal imports use `#pkg/*` aliases which map to `./src/*`. These are transformed to relative paths during compilation using `typescript-transform-paths`.
96+
97+
### Monorepo References
98+
99+
The root `tsconfig.json` contains references to all packages for TypeScript project references support.
100+
101+
### Build System
102+
103+
- Uses Turbo for orchestrating builds across packages
104+
- Custom `superturbo` wrapper in `platform/superturbo/`
105+
- Build outputs go to `dist/` directories
106+
107+
### Testing
108+
109+
- Test packages in `test/` directory
110+
- Package consumption tests ensure packages work correctly when installed
111+
112+
### Publishing
113+
114+
- Packages under `packages/` are published to npm
115+
- Uses Changesets for version management
116+
- Public packages use `@pkerschbaum/` scope
117+
118+
## Special Considerations
119+
120+
### TypeScript Patching
121+
122+
The repository uses a patched version of TypeScript to support custom transformers. We use the custom transformer (plugin) [`typescript-transform-paths`](https://github.com/LeDDGroup/typescript-transform-paths) in our TypeScript codebase. This enables authoring TypeScript sources with path aliases but during TypeScript compilation, they are replaced by relative paths. That avoids all sorts of difficulties supporting path aliases in Node.js, Next.js, etc.
123+
124+
Such custom transformers (plugins) are not supported by TypeScript out-of-the-box, so we apply [`ts-patch`](https://github.com/nonara/ts-patch) to the `typescript` package. To better incorporate with pnpm (<https://github.com/pnpm/pnpm/issues/6111>) we create a pnpm patch via `ts-patch`, using [`@pkerschbaum/pkg-management`](https://www.npmjs.com/package/@pkerschbaum/pkg-management).
125+
126+
When updating TypeScript to a new version, this procedure is required:
127+
128+
1. Remove current patch:
129+
130+
```bash
131+
pnpm patch-remove [email protected] # <-- look this up in package.json#pnpm.patchedDependencies
132+
```
133+
134+
2. Update `typescript` everywhere:
135+
136+
```bash
137+
pnpm -r update [email protected] # <-- new version here
138+
```
139+
140+
3. Run:
141+
142+
```bash
143+
pnpm --package="@pkerschbaum/[email protected]" dlx create-pnpm-patch-via-ts-patch \
144+
--typescript-version=5.6.3 \ # <-- new version of `typescript` here
145+
--ts-patch-version=3.3.0 # <-- latest version of `ts-patch` here
146+
```
147+
148+
In the future, when all tools (like Node.js, Next.js builds, Playwright, ...) support ["subpath imports"](https://nodejs.org/api/packages.html#subpath-imports) correctly, we can configure `#pkg/*` imports via subpath imports and remove that "patching" approach altogether.
149+
150+
### Git Hooks
151+
152+
- Husky is configured for git hooks
153+
- Pre-commit hooks run linting and formatting checks
154+
155+
### CI/CD
156+
157+
- GitHub Actions workflows handle testing and publishing
158+
- Changesets manage versioning and changelogs

‎README.md‎

Lines changed: 4 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88

99
## Development
1010

11+
For detailed information about the repository structure, conventions, and development practices, see [CLAUDE.md](./CLAUDE.md).
12+
1113
### Prerequisites
1214

1315
- **Node.js:** It is recommended to use [nvm](https://github.com/nvm-sh/nvm) and run `nvm use`, this will automatically switch to the Node.js version mentioned in the file [`.nvmrc`](./.nvmrc).
@@ -25,50 +27,12 @@
2527

2628
### Build & Run
2729

28-
1. **Install all dependencies:**
29-
30-
```sh
31-
pnpm install
32-
```
33-
34-
1. **Run an initial build:**
35-
36-
```sh
37-
pnpm run build
38-
```
30+
See [Common Commands in CLAUDE.md](./CLAUDE.md#common-commands) for build and development commands.
3931

4032
### Additional commands for development
4133

4234
See `scripts` of [`./package.json`](./package.json) for available scripts in the workspace.
4335

4436
## Updating TypeScript
4537

46-
We use the custom transformer (plugin) [`typescript-transform-paths`](https://github.com/LeDDGroup/typescript-transform-paths) in our TypeScript codebase. This enables authoring TypeScript sources with path aliases but during TypeScript compilation, they are replaced by relative paths.
47-
That avoids all sorts of difficulties supporting path aliases in Node.js, Next.js, etc.
48-
49-
Such custom transformers (plugins) are not supported by TypeScript out-of-the-box, so we apply [`ts-patch`](https://github.com/nonara/ts-patch) to the `typescript` package.
50-
To better incorporate with pnpm (<https://github.com/pnpm/pnpm/issues/6111>) we create a pnpm patch via `ts-patch`, using [`@pkerschbaum/pkg-management`](https://www.npmjs.com/package/@pkerschbaum/pkg-management).
51-
52-
Consequently, to update TypeScript to a new version, this procedure is required:
53-
54-
1. Remove current patch:
55-
56-
```bash
57-
pnpm patch-remove [email protected] # <-- look this up in package.json#pnpm.patchedDependencies
58-
```
59-
60-
1. Update `typescript` everywhere:
61-
62-
```bash
63-
pnpm -r update [email protected] # <-- new version here
64-
```
65-
66-
1. Run:
67-
68-
```bash
69-
pnpm --package="@pkerschbaum/[email protected]" dlx create-pnpm-patch-via-ts-patch \
70-
--typescript-version=5.6.3 \ # <-- new version of `typescript` here
71-
--ts-patch-version=3.3.0 # <-- latest version of `ts-patch` here
72-
```
73-
74-
In the future, when all tools (like Node.js, Next.js builds, Playwright, ...) support ["subpath imports"](https://nodejs.org/api/packages.html#subpath-imports) correctly, we can configure `#pkg/*` imports via subpath imports and remove that "patching" approach altogether.
38+
See [TypeScript Patching in CLAUDE.md](./CLAUDE.md#typescript-patching) for detailed instructions on updating TypeScript with our custom transformer setup.

‎packages/CLAUDE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Packages Directory
2+
3+
This directory contains the main packages that are published to npm under the `@pkerschbaum/` scope.
4+
5+
## Package Categories
6+
7+
### Utility Libraries
8+
9+
- `commons-ecma`: ECMAScript utilities
10+
- `commons-node`: Node.js specific utilities
11+
- `runtime-extensions-node`: Node.js runtime extensions
12+
13+
### Applications/CLIs
14+
15+
- `pk-cli`: CLI tool with various commands
16+
- `fetch-sitemap-locations`: Sitemap fetching utility
17+
18+
### Codemods
19+
20+
- `codemod-rewrite-module-specifiers-to-full-paths`: Path rewriting
21+
- `pk-web-stack-codemods`: Web stack setup codemods

‎platform/CLAUDE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Platform Directory
2+
3+
This directory contains internal platform utilities that support the development workflow across the monorepo.
4+
5+
## Package Categories
6+
7+
### Developer Tools
8+
9+
- `eslint-plugin-code-import-patterns`: Custom ESLint rules
10+
- `typescript-eslint-rules-requiring-type-info`: TypeScript ESLint utilities
11+
- `pkg-management`: Package management tools
12+
- `pkg-consumption-test`: Testing package consumption
13+
14+
### Build Configuration
15+
16+
- `config-eslint`: Shared ESLint configuration
17+
- `config-typescript`: Shared TypeScript configuration
18+
- `superturbo`: Custom Turbo wrapper for build orchestration

‎test/CLAUDE.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Test Directory
2+
3+
This directory contains test packages that ensure the quality and correctness of the packages in this monorepo.
4+
5+
## Purpose
6+
7+
Test packages in this directory are used to verify that packages work correctly when installed and consumed by external projects. This includes testing package exports, TypeScript types, and runtime behavior.

0 commit comments

Comments
 (0)