Skip to content

Commit cdac158

Browse files
prosdevprosdev
committed
feat: add TypeScript Monorepo kit
Production-ready monorepo blueprint with PNPM, Turborepo, and modern tooling
1 parent 9734f2e commit cdac158

File tree

3 files changed

+282
-3
lines changed

3 files changed

+282
-3
lines changed

‎components/site-footer.tsx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,8 @@ export function SiteFooter() {
5555
{/* Copyright */}
5656
<div className="mt-8 pt-6 border-t">
5757
<p className="text-xs text-muted-foreground text-center sm:text-left">
58-
© {new Date().getFullYear()} prosdevlab. Built to survive contact
59-
with reality.
58+
© {new Date().getFullYear()} prosdevlab. For those who like to
59+
build.
6060
</p>
6161
</div>
6262
</div>

‎content/kits/3.ts-monorepo.mdx‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
---
2+
title: TS Monorepo Starter
3+
slug: ts-monorepo
4+
status: stable
5+
summary: Clone, remove .git, and re-init for a no-fuss, production-ready blueprint for building complex TypeScript projects with modern tooling.
6+
tags:
7+
- monorepo
8+
- typescript
9+
- pnpm
10+
- turborepo
11+
- starter-template
12+
lastUpdated: 2026-01-03
13+
reference:
14+
type: repo
15+
url: https://github.com/prosdevlab/ts-monorepo
16+
category: sdk
17+
featured: true
18+
---
19+
20+
## Overview
21+
22+
TypeScript Monorepo is a starter template built from production experience. It provides a foundation for complex TypeScript projects with sensible defaults and modern tooling. Clone it, remove `.git`, reinitialize, and adapt it to your needs.
23+
24+
**Practical Note:** Use Claude or Cursor to reconfigure this template as a base for new monorepos. AI assistants can quickly adjust naming, structure, and tooling choices to match your project requirements.
25+
26+
## What You Get
27+
28+
A middle ground between minimal starters and opinionated frameworks:
29+
30+
- **Configured but Flexible** - Defaults that work, change what you need
31+
- **PNPM + Turborepo** - Fast installs, intelligent build caching
32+
- **Release Management** - Changesets, conventional commits, CI/CD included
33+
- **Current Tooling** - Latest LTS versions, regular maintenance
34+
- **Framework Agnostic** - Pure TypeScript, add frameworks as needed
35+
36+
## Stack at a Glance
37+
38+
**Build System:**
39+
- **PNPM** - Fast, disk-efficient package management with workspaces
40+
- **Turborepo** - High-performance build system with intelligent caching
41+
- **tsup** - Zero-config bundling with TypeScript, ESM by default
42+
43+
**Code Quality:**
44+
- **Biome** - Rust-powered linting and formatting (replaces ESLint + Prettier)
45+
- **TypeScript** - Strict mode, modern Node LTS settings
46+
- **Vitest** - Fast unit testing with native ESM support
47+
48+
**Developer Experience:**
49+
- **Volta** - Automatic Node.js and PNPM version management
50+
- **Commitlint** - Enforce conventional commits
51+
- **Husky** - Git hooks for quality gates
52+
- **Changesets** - Semantic versioning and changelog generation
53+
54+
**CI/CD:**
55+
- **GitHub Actions** - Automated testing, type checking, and npm publishing
56+
- **Release Automation** - Version bumps and publishing handled automatically
57+
58+
## Quick Start
59+
60+
```bash
61+
# Clone and reset git history
62+
git clone https://github.com/prosdevlab/ts-monorepo.git my-project
63+
cd my-project
64+
rm -rf .git
65+
git init
66+
67+
# Install (Volta handles Node.js and pnpm versions automatically)
68+
pnpm install
69+
70+
# Build all packages
71+
pnpm build
72+
73+
# Run tests
74+
pnpm test
75+
76+
# Start developing
77+
pnpm -F "@monorepo/core" dev
78+
```
79+
80+
## Project Structure
81+
82+
```bash
83+
my-project/
84+
├── packages/
85+
│ ├── core/ Core package (ESM)
86+
│ ├── utils/ Shared utilities
87+
│ └── feature-a/ Feature-specific package
88+
├── .changeset/ Version management
89+
├── .github/workflows/ CI/CD pipelines
90+
├── .husky/ Git hooks
91+
├── biome.json Lint + format config
92+
├── turbo.json Build caching config
93+
└── vitest.config.ts Test config
94+
```
95+
96+
Each package has:
97+
- Independent `package.json` (workspace protocol for internal deps)
98+
- Own `tsconfig.json` extending root config
99+
- TypeScript source in `src/`, built output in `dist/`
100+
101+
## Development Workflow
102+
103+
### Adding a New Package
104+
105+
```bash
106+
# Create package structure
107+
mkdir -p packages/my-package/src
108+
cd packages/my-package
109+
110+
# Add package.json
111+
cat > package.json << 'EOF'
112+
{
113+
"name": "@monorepo/my-package",
114+
"version": "0.1.0",
115+
"type": "module",
116+
"private": true,
117+
"exports": {
118+
".": {
119+
"types": "./dist/index.d.ts",
120+
"default": "./dist/index.js"
121+
}
122+
},
123+
"scripts": {
124+
"build": "tsup",
125+
"dev": "tsup --watch",
126+
"test": "vitest"
127+
},
128+
"dependencies": {
129+
"@monorepo/core": "workspace:*"
130+
}
131+
}
132+
EOF
133+
```
134+
135+
Update root `tsconfig.json` with path mappings, and you're ready to build.
136+
137+
### Making Changes
138+
139+
```bash
140+
# Create branch
141+
git checkout -b feat/my-feature
142+
143+
# Make changes, commit with conventional format
144+
git commit -m "feat(core): add new API method"
145+
146+
# Add changeset to document the change
147+
pnpm changeset
148+
# → Select packages affected
149+
# → Choose version bump (major/minor/patch)
150+
# → Write user-facing changelog
151+
152+
# Push and PR
153+
git push origin feat/my-feature
154+
```
155+
156+
### Building and Testing
157+
158+
```bash
159+
# Build everything (with Turborepo caching)
160+
pnpm build
161+
162+
# Build specific package
163+
pnpm -F "@monorepo/core" build
164+
165+
# Watch mode for development
166+
pnpm -F "@monorepo/core" dev
167+
168+
# Run all tests
169+
pnpm test
170+
171+
# Test a specific package with watch mode
172+
pnpm -F "@monorepo/core" test:watch
173+
```
174+
175+
## Publishing to npm
176+
177+
Packages are `"private": true` by default to prevent accidental publishing. To publish:
178+
179+
1. **Update `package.json`:**
180+
```json
181+
{
182+
"private": false,
183+
"publishConfig": {
184+
"access": "public"
185+
}
186+
}
187+
```
188+
189+
2. **Set npm token:**
190+
- Generate token at [npmjs.com](https://www.npmjs.com/settings/tokens)
191+
- Add as `NPM_TOKEN` secret in GitHub repo settings
192+
193+
3. **Merge to main:**
194+
- Changesets creates a version PR automatically
195+
- Merge the PR → packages publish to npm
196+
197+
## Why These Tools?
198+
199+
**PNPM over npm/yarn:**
200+
- Symlinked node_modules (saves disk space)
201+
- Strict dependency resolution (no phantom deps)
202+
- Fastest install times
203+
204+
**Turborepo over Lerna/Nx:**
205+
- Remote caching (share builds across team)
206+
- Incremental builds (only rebuild what changed)
207+
- Minimal config for TypeScript monorepos
208+
209+
**tsup over tsc/Rollup/webpack:**
210+
- Minimal config (sensible defaults)
211+
- Fast builds (esbuild under the hood)
212+
- ESM + types in one command
213+
214+
**Biome over ESLint + Prettier:**
215+
- 25x faster (Rust implementation)
216+
- Single tool (no config conflicts)
217+
- Drop-in compatible with Prettier/ESLint rules
218+
219+
**Changesets over semantic-release:**
220+
- Human-in-the-loop versioning
221+
- Package-specific changelogs
222+
- Monorepo-first design
223+
224+
## Use Cases
225+
226+
Works well for:
227+
- Multi-package libraries (shared core with optional plugins)
228+
- Design systems (components, utilities, themes as separate packages)
229+
- Microservices tooling (shared types, configs, utilities)
230+
- SDK ecosystems (core SDK with platform-specific adapters)
231+
232+
Less suitable for:
233+
- Single-package projects (simpler setup is sufficient)
234+
- Framework-specific apps (Next.js, Remix have optimized starters)
235+
236+
## Migration from Existing Project
237+
238+
```bash
239+
# 1. Clone this template
240+
git clone https://github.com/prosdevlab/ts-monorepo.git new-monorepo
241+
cd new-monorepo
242+
rm -rf .git
243+
244+
# 2. Copy your existing packages
245+
cp -r ../old-project/packages/* packages/
246+
247+
# 3. Update package.json files to use workspace protocol
248+
# Example: "@my-org/core": "^1.0.0" → "@my-org/core": "workspace:*"
249+
250+
# 4. Install and build
251+
pnpm install
252+
pnpm build
253+
254+
# 5. Run tests to verify everything works
255+
pnpm test
256+
```
257+
258+
## What's Included
259+
260+
- **CI/CD workflows** - Lint, test, type check, publish automation
261+
- **Git hooks** - Pre-commit linting, commit message validation
262+
- **Version management** - Changesets for semantic versioning
263+
- **TypeScript** - Strict mode with project references
264+
- **Build system** - Turborepo caching, tsup bundling
265+
- **ESM modules** - Native ES modules throughout
266+
- **Testing** - Vitest with coverage and watch mode
267+
- **Documentation** - CONTRIBUTING.md and AGENTS.md for AI context
268+
269+
## License
270+
271+
MIT - Do whatever you want with it. No attribution required.
272+
273+
## Resources
274+
275+
- [GitHub Repository](https://github.com/prosdevlab/ts-monorepo)
276+
- [Turborepo Docs](https://turbo.build/repo/docs)
277+
- [PNPM Workspaces](https://pnpm.io/workspaces)
278+
- [Changesets Guide](https://github.com/changesets/changesets)
279+

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"version": "0.1.0",
44
"private": true,
55
"scripts": {
6-
"dev": "next dev",
6+
"dev": "velite && next dev",
77
"build": "velite && next build",
88
"start": "next start",
99
"lint": "biome check",

0 commit comments

Comments
 (0)