devstack 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +148 -97
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,25 +1,81 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# ⚡ devstack
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Ship your full-stack app in minutes, not days.**
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
CLI scaffold generator that creates production-ready monorepo projects with\
|
|
8
|
+
Bun, Turborepo, React 19, Hono, Drizzle ORM, and PostgreSQL.
|
|
8
9
|
|
|
9
|
-
|
|
10
|
+
[](https://www.npmjs.com/package/devstack)
|
|
11
|
+
[](https://www.npmjs.com/package/devstack)
|
|
12
|
+
[](LICENSE)
|
|
13
|
+
[](https://www.typescriptlang.org/)
|
|
14
|
+
[](https://bun.sh)
|
|
15
|
+
[](https://github.com/pedronauck/devstack/stargazers)
|
|
10
16
|
|
|
11
|
-
|
|
17
|
+
<br />
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
```bash
|
|
20
|
+
bunx devstack
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
<br />
|
|
24
|
+
|
|
25
|
+
[Getting Started](#-getting-started) · [Stack Models](#-stack-models) · [Modules](#-modules) · [AI Layer](#-ai-agent-intelligence-layer) · [Contributing](#-contributing)
|
|
26
|
+
|
|
27
|
+
</div>
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 🧐 Why devstack?
|
|
32
|
+
|
|
33
|
+
Every new project starts the same way — days wiring up linters, formatters, auth, payments, Docker, CI, database migrations… **devstack eliminates that entirely.** Run one command, pick your stack and modules, and get a production-grade monorepo with everything already connected.
|
|
14
34
|
|
|
15
|
-
|
|
16
|
-
- **Modular architecture** — pick only what you need from 9 optional modules (auth, payments, email, storage, etc.)
|
|
17
|
-
- **Production-ready defaults** — Oxlint, Oxfmt, Vitest, Husky, Conventional Commits, GitHub Actions CI
|
|
18
|
-
- **Docker Compose infrastructure** — PostgreSQL, Redis, MinIO, Inngest, Mailpit — all pre-configured
|
|
19
|
-
- **AI-native projects** — generated `CLAUDE.md` with skill dispatch protocol, architecture docs, and agent skill files
|
|
20
|
-
- **Template overlays** — modules contribute files, env vars, Docker services, and dependencies that merge cleanly into the base project
|
|
35
|
+
Every generated project also ships with an **AI agent intelligence layer** — pre-configured `CLAUDE.md` and skill files that give Claude Code (and other AI agents) deep context about your project's architecture, conventions, and tooling.
|
|
21
36
|
|
|
22
|
-
##
|
|
37
|
+
## ✨ Features
|
|
38
|
+
|
|
39
|
+
- 🏗️ **Two stack models** — separated API + SPA or fullstack SSR
|
|
40
|
+
- 🧩 **9 optional modules** — auth, payments, email, storage, background jobs, and more
|
|
41
|
+
- 🔧 **Production-ready defaults** — Oxlint, Oxfmt, Vitest, Husky, Conventional Commits, GitHub Actions
|
|
42
|
+
- 🐳 **Docker Compose infra** — PostgreSQL, Redis, MinIO, Inngest, Mailpit — all pre-configured
|
|
43
|
+
- 🤖 **AI-native projects** — `CLAUDE.md` with skill dispatch protocol, architecture docs, agent skills
|
|
44
|
+
- 📦 **Template overlays** — modules contribute files, env vars, Docker services, and deps that merge cleanly
|
|
45
|
+
|
|
46
|
+
## 🚀 Getting Started
|
|
47
|
+
|
|
48
|
+
### Prerequisites
|
|
49
|
+
|
|
50
|
+
| Requirement | Version |
|
|
51
|
+
| --------------------------------------------- | -------- |
|
|
52
|
+
| [Bun](https://bun.sh) | >= 1.2.0 |
|
|
53
|
+
| [Docker](https://docs.docker.com/get-docker/) | Latest |
|
|
54
|
+
| Git | Any |
|
|
55
|
+
|
|
56
|
+
### Usage
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
# Run the interactive CLI
|
|
60
|
+
bunx devstack
|
|
61
|
+
|
|
62
|
+
# Follow the prompts:
|
|
63
|
+
# 1. App name (e.g., my-saas)
|
|
64
|
+
# 2. Target directory
|
|
65
|
+
# 3. Stack model (Separated or TanStack Start)
|
|
66
|
+
# 4. Optional modules
|
|
67
|
+
# 5. Install dependencies (yes/no)
|
|
68
|
+
# 6. Initialize git (yes/no)
|
|
69
|
+
|
|
70
|
+
# Start building
|
|
71
|
+
cd my-saas
|
|
72
|
+
docker compose up -d
|
|
73
|
+
bun run dev
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## 🏗️ Stack Models
|
|
77
|
+
|
|
78
|
+
Choose the architecture that fits your project:
|
|
23
79
|
|
|
24
80
|
### Separated (Hono API + Vite React)
|
|
25
81
|
|
|
@@ -31,9 +87,19 @@ packages/
|
|
|
31
87
|
└── backend/ # Hono + Drizzle ORM + PostgreSQL + Zod OpenAPI
|
|
32
88
|
```
|
|
33
89
|
|
|
34
|
-
|
|
90
|
+
<details>
|
|
91
|
+
<summary><strong>Frontend details</strong></summary>
|
|
92
|
+
|
|
93
|
+
React 19, Vite 8, TanStack Router (file-based), TanStack Query, Zustand, shadcn/ui (50+ components), Tailwind v4 with oklch color tokens, dark mode.
|
|
35
94
|
|
|
36
|
-
|
|
95
|
+
</details>
|
|
96
|
+
|
|
97
|
+
<details>
|
|
98
|
+
<summary><strong>Backend details</strong></summary>
|
|
99
|
+
|
|
100
|
+
Hono v4 with Zod OpenAPI, Scalar API docs, Drizzle ORM, LogTape logging, Prometheus metrics, structured error handling. Follows a **route → usecase → repository** layered architecture.
|
|
101
|
+
|
|
102
|
+
</details>
|
|
37
103
|
|
|
38
104
|
### TanStack Start (Fullstack SSR)
|
|
39
105
|
|
|
@@ -41,28 +107,31 @@ Single package with server functions and SSR:
|
|
|
41
107
|
|
|
42
108
|
```
|
|
43
109
|
packages/
|
|
44
|
-
└── app/
|
|
110
|
+
└── app/
|
|
45
111
|
├── src/routes/ # File-based routes (UI + API)
|
|
46
112
|
└── server/ # Server-only code (db, lib)
|
|
47
113
|
```
|
|
48
114
|
|
|
49
115
|
Same UI layer (shadcn/ui, Tailwind v4, TanStack Query) with server functions replacing the separate API.
|
|
50
116
|
|
|
51
|
-
## Modules
|
|
117
|
+
## 🧩 Modules
|
|
52
118
|
|
|
53
|
-
All modules are optional
|
|
119
|
+
All modules are optional — pick any combination during scaffolding:
|
|
54
120
|
|
|
55
|
-
| Module
|
|
56
|
-
|
|
|
57
|
-
| **Authentication** | Better Auth with email/password sessions
|
|
58
|
-
| **Organizations** | Multi-tenant org membership and roles (requires Auth) |
|
|
59
|
-
| **Stripe** | Plans, subscriptions, and webhook handling
|
|
60
|
-
| **Storage** | S3/MinIO object storage with presigned URLs
|
|
61
|
-
| **Email** | Resend + SMTP fallback + React Email templates
|
|
62
|
-
| **Inngest** | Background jobs with local dev server
|
|
63
|
-
| **Observability** | OpenTelemetry tracing + Sentry error tracking
|
|
64
|
-
| **Redis** | Redis client + rate limiting middleware
|
|
65
|
-
| **Storybook** | Component documentation workspace + Chromatic
|
|
121
|
+
| Module | What it adds |
|
|
122
|
+
| --------------------- | ------------------------------------------------------- |
|
|
123
|
+
| 🔐 **Authentication** | Better Auth with email/password sessions |
|
|
124
|
+
| 🏢 **Organizations** | Multi-tenant org membership and roles _(requires Auth)_ |
|
|
125
|
+
| 💳 **Stripe** | Plans, subscriptions, and webhook handling |
|
|
126
|
+
| 📁 **Storage** | S3/MinIO object storage with presigned URLs |
|
|
127
|
+
| 📧 **Email** | Resend + SMTP fallback + React Email templates |
|
|
128
|
+
| ⚙️ **Inngest** | Background jobs with local dev server |
|
|
129
|
+
| 📡 **Observability** | OpenTelemetry tracing + Sentry error tracking |
|
|
130
|
+
| 🔴 **Redis** | Redis client + rate limiting middleware |
|
|
131
|
+
| 📖 **Storybook** | Component documentation workspace + Chromatic |
|
|
132
|
+
|
|
133
|
+
<details>
|
|
134
|
+
<summary><strong>How modules work</strong></summary>
|
|
66
135
|
|
|
67
136
|
Modules declare dependencies — selecting **Organizations** automatically includes **Authentication**. Each module contributes:
|
|
68
137
|
|
|
@@ -72,35 +141,11 @@ Modules declare dependencies — selecting **Organizations** automatically inclu
|
|
|
72
141
|
- Template files (overlaid onto the base project)
|
|
73
142
|
- CLAUDE.md sections and agent skill files
|
|
74
143
|
|
|
75
|
-
|
|
144
|
+
</details>
|
|
76
145
|
|
|
77
|
-
|
|
78
|
-
- [Docker](https://docs.docker.com/get-docker/) (for infrastructure services)
|
|
79
|
-
- Git
|
|
146
|
+
## 📂 Generated Project Structure
|
|
80
147
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
# Run the CLI
|
|
85
|
-
bunx devstack
|
|
86
|
-
|
|
87
|
-
# Follow the prompts:
|
|
88
|
-
# 1. App name (e.g., my-saas)
|
|
89
|
-
# 2. Target directory
|
|
90
|
-
# 3. Stack model (Separated or TanStack Start)
|
|
91
|
-
# 4. Optional modules
|
|
92
|
-
# 5. Install dependencies (yes/no)
|
|
93
|
-
# 6. Initialize git (yes/no)
|
|
94
|
-
|
|
95
|
-
# Start your project
|
|
96
|
-
cd my-saas
|
|
97
|
-
docker compose up -d
|
|
98
|
-
bun run dev
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
## Generated Project Structure
|
|
102
|
-
|
|
103
|
-
A project generated with the **Separated** stack and **Auth + Stripe** modules:
|
|
148
|
+
> A project generated with the **Separated** stack and **Auth + Stripe** modules:
|
|
104
149
|
|
|
105
150
|
```
|
|
106
151
|
my-saas/
|
|
@@ -112,7 +157,6 @@ my-saas/
|
|
|
112
157
|
│ │ │ ├── lib/ # Utilities, API client
|
|
113
158
|
│ │ │ ├── routes/ # TanStack Router (file-based)
|
|
114
159
|
│ │ │ └── stores/ # Zustand stores
|
|
115
|
-
│ │ ├── package.json
|
|
116
160
|
│ │ └── vite.config.ts
|
|
117
161
|
│ └── backend/ # Hono API
|
|
118
162
|
│ ├── src/
|
|
@@ -121,14 +165,12 @@ my-saas/
|
|
|
121
165
|
│ │ ├── db/ # Drizzle schema + migrations
|
|
122
166
|
│ │ ├── lib/ # Auth client, Stripe client
|
|
123
167
|
│ │ └── env.ts # Zod-validated environment
|
|
124
|
-
│ ├── package.json
|
|
125
168
|
│ └── drizzle.config.ts
|
|
126
169
|
├── .claude/
|
|
127
170
|
│ ├── settings.json # Allowed/denied commands for Claude Code
|
|
128
171
|
│ └── skills/ # Agent skill files
|
|
129
172
|
├── .github/
|
|
130
173
|
│ └── workflows/ci.yaml # PR validation + make check
|
|
131
|
-
├── lint-plugins/ # Custom Oxlint rules
|
|
132
174
|
├── docker-compose.yaml # PostgreSQL + module services
|
|
133
175
|
├── turbo.json # Turborepo task graph
|
|
134
176
|
├── Makefile # check, test, lint, fmt, db-reset
|
|
@@ -136,42 +178,45 @@ my-saas/
|
|
|
136
178
|
└── AGENTS.md # Same as CLAUDE.md (for Codex)
|
|
137
179
|
```
|
|
138
180
|
|
|
139
|
-
## Generated Tooling
|
|
140
|
-
|
|
141
|
-
Every generated project includes:
|
|
181
|
+
## 🔧 Generated Tooling
|
|
142
182
|
|
|
143
|
-
|
|
144
|
-
| ----------------------- | ------------------------------------------ |
|
|
145
|
-
| **Bun** | Package manager and runtime |
|
|
146
|
-
| **Turborepo** | Monorepo task orchestration |
|
|
147
|
-
| **Oxlint** | Fast linting (zero warnings policy) |
|
|
148
|
-
| **Oxfmt** | Fast formatting |
|
|
149
|
-
| **Vitest** | Unit and integration testing |
|
|
150
|
-
| **Husky + lint-staged** | Pre-commit hooks |
|
|
151
|
-
| **Commitlint** | Conventional Commits enforcement |
|
|
152
|
-
| **GitHub Actions** | CI pipeline (PR title + `make check`) |
|
|
153
|
-
| **Docker Compose** | PostgreSQL, Redis, MinIO, Inngest, Mailpit |
|
|
183
|
+
Every generated project includes a battle-tested toolchain:
|
|
154
184
|
|
|
155
|
-
|
|
185
|
+
| Tool | Purpose |
|
|
186
|
+
| -------------------------------------------------------- | ------------------------------------------ |
|
|
187
|
+
| [Bun](https://bun.sh) | Package manager and runtime |
|
|
188
|
+
| [Turborepo](https://turbo.build) | Monorepo task orchestration |
|
|
189
|
+
| [Oxlint](https://oxc.rs) | Fast linting (zero warnings policy) |
|
|
190
|
+
| [Oxfmt](https://oxc.rs) | Fast formatting |
|
|
191
|
+
| [Vitest](https://vitest.dev) | Unit and integration testing |
|
|
192
|
+
| [Husky](https://typicode.github.io/husky/) + lint-staged | Pre-commit hooks |
|
|
193
|
+
| [Commitlint](https://commitlint.js.org/) | Conventional Commits enforcement |
|
|
194
|
+
| [GitHub Actions](https://github.com/features/actions) | CI pipeline (PR title + `make check`) |
|
|
195
|
+
| [Docker Compose](https://docs.docker.com/compose/) | PostgreSQL, Redis, MinIO, Inngest, Mailpit |
|
|
156
196
|
|
|
157
|
-
|
|
197
|
+
## 🤖 AI Agent Intelligence Layer
|
|
158
198
|
|
|
159
|
-
|
|
199
|
+
Generated projects are designed to work seamlessly with AI coding agents:
|
|
160
200
|
|
|
161
|
-
|
|
201
|
+
| Layer | What it provides |
|
|
202
|
+
| -------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
203
|
+
| **CLAUDE.md / AGENTS.md** | Architecture overview, coding conventions, skill enforcement rules, and dispatch protocol |
|
|
204
|
+
| **Skill files** (`.claude/skills/`) | Domain-specific knowledge (React, Hono, Drizzle, Stripe, etc.) |
|
|
205
|
+
| **Settings** (`.claude/settings.json`) | Pre-approved safe commands and blocked destructive operations |
|
|
162
206
|
|
|
163
|
-
|
|
207
|
+
> [!TIP]
|
|
208
|
+
> The skill set is **stack-aware**: the Separated stack includes the `hono` skill while TanStack Start includes `tanstack-start-best-practices`. Module-specific skills are added based on your selections (e.g., `better-auth-best-practices`, `stripe-webhooks`).
|
|
164
209
|
|
|
165
|
-
|
|
210
|
+
## 🤝 Contributing
|
|
166
211
|
|
|
167
|
-
|
|
212
|
+
We welcome contributions! Here's how to get started:
|
|
168
213
|
|
|
169
214
|
### Setup
|
|
170
215
|
|
|
171
216
|
```bash
|
|
172
217
|
git clone https://github.com/pedronauck/devstack.git
|
|
173
218
|
cd devstack
|
|
174
|
-
git submodule update --init --recursive
|
|
219
|
+
git submodule update --init --recursive
|
|
175
220
|
bun install
|
|
176
221
|
```
|
|
177
222
|
|
|
@@ -183,10 +228,11 @@ bun run test # Run tests (Vitest)
|
|
|
183
228
|
bun run typecheck # Type-check with tsc
|
|
184
229
|
bun run lint # Format check (Oxfmt) + lint (Oxlint)
|
|
185
230
|
bun run format # Format all files
|
|
186
|
-
make check # format + lint-fix + typecheck + test
|
|
231
|
+
make check # Full pipeline: format + lint-fix + typecheck + test
|
|
187
232
|
```
|
|
188
233
|
|
|
189
|
-
|
|
234
|
+
<details>
|
|
235
|
+
<summary><strong>Project structure</strong></summary>
|
|
190
236
|
|
|
191
237
|
```
|
|
192
238
|
src/
|
|
@@ -214,28 +260,23 @@ tests/ # Vitest test suite
|
|
|
214
260
|
vendor/skills/ # Git submodule — agent skill source files
|
|
215
261
|
```
|
|
216
262
|
|
|
217
|
-
|
|
263
|
+
</details>
|
|
264
|
+
|
|
265
|
+
<details>
|
|
266
|
+
<summary><strong>How it works</strong></summary>
|
|
218
267
|
|
|
219
268
|
1. The CLI collects user choices (name, stack model, modules)
|
|
220
269
|
2. The resolver auto-includes transitive module dependencies
|
|
221
270
|
3. Base templates are copied to the target directory
|
|
222
271
|
4. Module template overlays are merged on top
|
|
223
|
-
5. Template tokens (`{{projectName}}`,
|
|
272
|
+
5. Template tokens (`{{projectName}}`, etc.) are replaced in all text files
|
|
224
273
|
6. Dynamic files are generated (package.json, docker-compose.yaml, CLAUDE.md, env.ts, turbo.json)
|
|
225
274
|
7. Module package contributions are deep-merged into the correct package.json files
|
|
226
275
|
8. Agent skill files are copied based on stack model + selected modules
|
|
227
276
|
9. All generated files are formatted with Oxfmt
|
|
228
277
|
10. Optionally: `bun install` and `git init` with initial commit
|
|
229
278
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
```bash
|
|
233
|
-
bun run test # All tests
|
|
234
|
-
bun run test:coverage # With coverage report
|
|
235
|
-
bunx vitest run tests/modules # Specific test file
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
Tests include unit tests for utilities and integration tests that scaffold real projects in temp directories and verify file contents.
|
|
279
|
+
</details>
|
|
239
280
|
|
|
240
281
|
### Commit Convention
|
|
241
282
|
|
|
@@ -248,6 +289,16 @@ refactor: extract shared builder functions
|
|
|
248
289
|
test: add integration tests for TanStack Start
|
|
249
290
|
```
|
|
250
291
|
|
|
251
|
-
## License
|
|
292
|
+
## 📄 License
|
|
293
|
+
|
|
294
|
+
MIT © [Pedro Nauck](https://github.com/pedronauck)
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
<div align="center">
|
|
299
|
+
|
|
300
|
+
**Built with ❤️ by [Pedro Nauck](https://github.com/pedronauck)**
|
|
301
|
+
|
|
302
|
+
⭐ If devstack saves you time, consider giving it a star!
|
|
252
303
|
|
|
253
|
-
|
|
304
|
+
</div>
|