Janna TypeScript Monorepo Assistant
This skill provides expert guidance for working with the Janna monorepo - a collection of stylized TypeScript/JavaScript developer toolkits including `@jannajs/lint`, `@jannajs/git-guards`, and more.
What This Skill Does
Guides development in a pnpm + turbo monorepo structureHelps implement and modify ESLint and commitlint configurationsAssists with git hook development and commit message processingProvides patterns for building and testing packagesEnsures ESM compatibility and proper TypeScript configurationsInstructions for AI Agent
1. Communication Principles
**CRITICAL - Solution Approach First:**
Unless directly instructed to generate code, ALWAYS provide a clear solution approach before implementingBreak down problems into logical stepsExplain reasoning behind proposed solutionsConsider alternative approaches when applicableHighlight potential impacts or considerationsOnly generate code when explicitly requested or after approach approval**Language Consistency:**
Always respond in the same language as the user's question2. Repository Structure
**Monorepo Layout:**
`packages/*` contains publishable packagesKey packages: - `packages/lint` - ESLint/commitlint helpers and templates
- `packages/git-guards` - Git hook helpers
**Important Files to Reference:**
1. `package.json` (root) - scripts and workspace setup
2. `packages/lint/README.md` - ESLint/commitlint patterns, VSCode config
3. `packages/lint/src/commit-msg-path-emojify.ts` - commit-msg hook logic
4. `.husky/commit-msg` - commit hook entry point
5. `packages/lint/templates/commitlint.config.ts` - commitlint template
3. Tooling Stack
**Package Management:**
Package manager: pnpm (see root `package.json` `packageManager` field)Task runner: turbo**Common Commands:**
```bash
Build all packages
pnpm build
Development mode
pnpm dev
Run tests (vitest)
pnpm test
Build single package
pnpm -w -s -F <package-name> build
Test single package
pnpm -w -F <package-name> test
Lint entire repo
pnpm -w lint
Clean caches and node_modules
pnpm run clean
```
**Module System:**
All packages use ES modules (`type: "module"` in package.json)Prefer ESM imports and .mjs/.ts entry pointsCheck `exports` and `types` fields in package.json for proper exports4. Commit and Hook Conventions
**Husky Integration:**
`.husky/commit-msg` runs `npx --no -- commitlint --edit $1`Commit message emojifier: `packages/lint/src/commit-msg-path-emojify.ts`Reads commit message, matches conventional commit types, inserts emoji (e.g., `feat` → ✨)**Commitlint:**
Templates at `packages/lint/templates/commitlint.config.ts`Extends `@commitlint/config-conventional`Key dependencies: `@commitlint/cli`, `@commitlint/config-conventional`, `@commitlint/is-ignored`**When Editing Commit Hook Logic:**
Reference `packages/lint/src/commit-msg-path-emojify.ts`Follow existing regex + emoji map patternsCheck template in `packages/lint/src/core.ts`5. Code Patterns and Conventions
**Package Structure:**
Small, focused packages exporting ESM and typesCheck `package.json` `exports` and `types` fieldsExample: `packages/lint/package.json`**CLI Helpers:**
Built with `commander` and `zx`Look for `bin/cli.mjs` and `src/cli` directoriesUse `zx`'s fs wrapper: `import { fs } from 'zx'`**Testing:**
Framework: VitestMocking: `vi.mocked()` and `vi.mock()`Example: `packages/lint/src/commit-msg-path-emojify.test.ts`**Build Configuration:**
TypeScript compilation + unbuildESM module format required6. External Dependencies
**ESLint:**
Peer dependency: `@antfu/eslint-config`Shapes project's ESLint conventions**Commitlint:**
Family: `@commitlint/cli`, `@commitlint/config-conventional`, `@commitlint/is-ignored`TypeScript ESM quirks documented in `packages/lint/README.md`Note discussion about `commitlint.config.ts` vs `.cts`7. Implementation Examples
**Modify Commit Hook Behavior:**
Edit `.husky/commit-msg`Modify `packages/lint/src/commit-msg-path-emojify.ts`Follow existing regex + emoji map patterns**Add New Package:**
Follow structure in `packages/*`Include `package.json` with: - `type: "module"`
- `exports` field
- Build scripts using tsc + unbuild
Set up proper TypeScript configuration8. Pre-Commit Safety Checks
Before committing changes, run:
1. **Build check:**
```bash
pnpm -w -s -F <package-name> build
```
2. **Test check:**
```bash
pnpm test
# or for specific package:
pnpm -w -F <package-name> test
```
3. **Lint check:**
```bash
pnpm -w lint
```
9. Workflow for Changes
1. **Understand the request** - break down what needs to be done
2. **Present solution approach** - explain steps before coding (unless code explicitly requested)
3. **Reference relevant files** - use the priority list in section 2
4. **Follow existing patterns** - check similar implementations in the codebase
5. **Implement changes** - maintain ESM compatibility and monorepo conventions
6. **Run safety checks** - build, test, lint before suggesting commit
7. **Follow commit conventions** - use conventional commit format with emojis
10. Constraints
Never break ESM compatibilityAlways maintain TypeScript type safetyFollow conventional commit format for all changesEnsure all packages build successfully before suggesting changesRespect pnpm workspace structureKeep packages small and focusedUsage Examples
**Example 1: Adding a new commit type emoji**
1. Read `packages/lint/src/commit-msg-path-emojify.ts`
2. Locate the emoji map
3. Add new mapping following existing pattern
4. Run `pnpm -w -s -F @jannajs/lint build`
5. Test with sample commit message
**Example 2: Creating a new package**
1. Create directory in `packages/<new-package>`
2. Set up package.json with ESM configuration
3. Add to turbo pipeline in root
4. Implement with TypeScript
5. Add tests with Vitest
6. Run `pnpm build` and `pnpm test`
**Example 3: Modifying ESLint config**
1. Review `packages/lint/README.md` for patterns
2. Check `@antfu/eslint-config` peer dependency
3. Propose approach before implementing
4. Update templates if needed
5. Test with `pnpm -w lint`
Notes
This is a developer toolkit monorepo - focus on DX and maintainabilityESM compatibility is non-negotiableCommit hook UX is critical - test thoroughlyWhen uncertain, ask for clarification before implementingRefer to package READMEs for package-specific details