saasaloy 0.3.0 → 0.5.0

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.
Files changed (4) hide show
  1. package/README.md +77 -91
  2. package/dist/index.js +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -2,61 +2,91 @@
2
2
 
3
3
  # Saasaloy
4
4
 
5
- **Open source, composable SaaS starter kit for Cloudflare.** A CLI plus a module registry, not a boilerplate. Think shadcn/ui for a full-stack SaaS: you scaffold a small base, then copy in the API, database, auth, and product features one command at a time, as source files you own.
5
+ **Open source, composable SaaS starter kit for Cloudflare.** A CLI plus a module registry, not a boilerplate. You scaffold a small base, then copy in the API, database, auth, billing and product features one command at a time, as source files you own. Think shadcn/ui for a full-stack SaaS.
6
6
 
7
7
  [![npm version](https://img.shields.io/npm/v/saasaloy)](https://www.npmjs.com/package/saasaloy)
8
8
  [![CI](https://github.com/mimukit/saasaloy/actions/workflows/ci.yml/badge.svg)](https://github.com/mimukit/saasaloy/actions/workflows/ci.yml)
9
9
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
10
10
 
11
- ## Why Saasaloy
11
+ > [!WARNING]
12
+ > **Saasaloy is at a very early stage.** It is a working proof of concept, not a finished product. Use it at your own risk, and do not build a production project on it yet. The CLI, the module contracts, the generated code and the conventions can all change or break between releases until a stable `1.x.x` version ships. Pin the version you install, read the changelog before you update, and expect to do some manual merging along the way.
12
13
 
13
- - **You own the code.** Nothing is imported from a Saasaloy package at runtime. The CLI writes files into your repo and gets out of the way.
14
- - **Start small, add on demand.** `saasaloy init` gives you a landing page and a UI package. API, database, auth, admin, email, SMS, and features arrive later with `saasaloy add`, each with its dependencies resolved.
15
- - **Cloudflare-native, near zero cost.** Workers, D1, and static assets by default. Most modules run on the free tier, and the ones that do not say so up front.
16
- - **Agent-native.** Every generated project ships `AGENTS.md`, `CLAUDE.md`, a `DESIGN.md` contract, and per-module skills for Claude Code and other agents.
17
- - **Reversible.** `saasaloy remove` undoes a module from its manifest, and `saasaloy update` re-applies at a newer version with a merge plan for your edits.
14
+ ## Why Saasaloy exists
15
+
16
+ You know the feeling. It is Saturday morning, you have an idea, and you are sure about it. You open a terminal to build the landing page. Three hours later you are wiring up OAuth callbacks, picking an ORM, arguing with yourself about multi-tenancy, and the landing page does not exist yet. By Sunday night you have a login screen, an empty admin panel and no idea whether a single person wants the product.
17
+
18
+ Every technical founder has a folder of dead SaaS projects. Open one. There is a polished auth flow, a role system, a Stripe webhook handler with retries, a multi-tenant schema with careful indexes. But there are no real users. The idea was never tested because the builder spent the first month building the parts every SaaS needs and never reached the part that made this one different.
19
+
20
+ In the age of AI, a vibe-coded demo takes an afternoon. A production-grade SaaS still takes the same components it always did: API, database, auth, admin, teams, billing, email, jobs, rate limits. Each one has to be crafted with precision. None of them proves that your idea is worth building.
21
+
22
+ The ready-made boilerplates promise to fix this, and they make it worse. You clone one and inherit forty features, twelve environment variables and someone else's opinions about billing, all on a day when the only thing you need is a form that collects email addresses. You spend the first week deleting code instead of testing an idea.
23
+
24
+ Saasaloy starts the other way around. Saasaloy is built on one rule: a SaaS has stages, and the code scaffold should match the stage. `saasaloy init` gives you a landing page and nothing else. Proably then add a waitlist module to collect potential customer's data. When the waitlist fills up, you add auth to make them registered users. When users ask for a team account, you add teams and tenancy. When someone wants to pay, you add billing. Every module is production-grade code copied into your repo, arriving on the day the product earns it, and not one day sooner.
25
+
26
+ The second philosophy is that validation stage of a SaaS idea should be free. Saasaloy is Cloudflare-native serverless architecture by default, it runs on Cloudflare by default because you never should be worried about server managment and cost just to explore your SaaS ideas. Workers, D1, KV and R2 keep most modules on the free tier, so you can go from a Saturday idea to a first paying customer with a hosting bill close to zero.
27
+
28
+ Cloudflare is the default, not the cage. Every vendor sits behind a swappable provider, and every capability ships a console or in-memory version so you can build the whole thing offline, with no cloud account at all.
29
+
30
+ These are the reasons behind the born of Saasaloy.
31
+
32
+ ## How it works
33
+
34
+ - **You own the code.** Nothing is imported from a Saasaloy package at runtime. The CLI writes files into your repo and gets out of the way. Edit anything.
35
+ - **Start small, add on demand.** `saasaloy init` gives you an Astro landing page and a UI package. Everything else arrives with `saasaloy add <module>`, with its dependencies resolved and installed first.
36
+ - **Swappable providers.** `email`, `sms`, `queue`, `kv`, `storage`, `logger` and `billing` each expose one interface. Pick the vendor with a `*_PROVIDER` env var, or drop in a `-console` or `-memory` provider for local work.
37
+ - **Agent-native.** Every generated project ships `AGENTS.md`, `CLAUDE.md`, a `DESIGN.md` contract, and a skill per installed module for Claude Code and other coding agents.
38
+ - **Reversible and updatable.** `saasaloy remove` undoes a module from its manifest. `saasaloy update` re-applies the base and modules at a newer version with a merge plan for the files you edited.
39
+
40
+ The full picture of how the CLI, the registry and a generated project fit together is in [Architecture](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/architecture.md).
18
41
 
19
42
  ## Quick start
20
43
 
21
44
  Requires Node 24.13.0+ and pnpm 11+. No Cloudflare account is needed until you deploy.
22
45
 
23
46
  ```bash
24
- npm install -g saasaloy # or: pnpm add -g saasaloy, or prefix commands with npx
47
+ npm install -g saasaloy
48
+ # or: pnpm add -g saasaloy, or prefix commands with npx
49
+
25
50
  saasaloy init my-app
26
51
  cd my-app
27
52
  pnpm install
28
- pnpm dev # landing page on http://localhost:3000
53
+
54
+ pnpm dev
55
+
56
+ # landing page on http://localhost:3000
29
57
  ```
30
58
 
31
- Then compose the product:
59
+ Then add modules as the product grows:
32
60
 
33
61
  ```bash
34
- saasaloy list # what the registry offers, and what you already have
35
- saasaloy add database-d1 # pulls api + database, then binds them to D1 (or pick database-postgres)
36
- saasaloy add admin # pulls auth, then an auth-gated admin SPA
37
- saasaloy add waitlist # a feature: form, API route, table
38
- saasaloy env # fill in the variables your modules declare (--check gates a deploy)
39
- ```
62
+ saasaloy list
63
+ # what the registry offers, and what you already have
64
+
65
+ saasaloy add waitlist
66
+ # pulls api, validators and database, then asks for a database driver
40
67
 
41
- Full walkthrough: [Getting started](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/getting-started.md), then [Make the project yours](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/make-it-yours.md) for the bundled skills that write your product brief, landing copy, and theme.
42
-
43
- ## What you get
44
-
45
- ```text
46
- my-app/
47
- apps/web/ Astro landing page (the base)
48
- apps/api/ Hono Worker (saasaloy add api)
49
- apps/admin/ TanStack Router SPA (saasaloy add admin)
50
- packages/ui/ shared React + Tailwind components
51
- packages/db/ Drizzle schema + client (saasaloy add database-d1 | database-postgres)
52
- packages/auth/ Better Auth (saasaloy add auth)
53
- packages/email/ email provider interface (saasaloy add email)
54
- packages/queue/ background jobs + schedules (saasaloy add queue)
55
- .agents/skills/ agent skills, symlinked from .claude/skills/
56
- DESIGN.md the design contract
57
- saasaloy.json installed modules + alias map
68
+ saasaloy add admin
69
+ # pulls auth, then an auth-gated admin SPA
58
70
  ```
59
71
 
72
+ `saasaloy add <name> --dry-run` prints what a module would do to your project before it does it.
73
+
74
+ Full walkthrough: [Getting started](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/getting-started.md), then [Make the project yours](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/make-it-yours.md) for the bundled skills that write your product brief, landing copy and theme.
75
+
76
+ ## A project through its stages
77
+
78
+ | Stage | What you need | What you add |
79
+ |---|---|---|
80
+ | Validate the idea | a landing page and a waitlist | `init`, then `waitlist` |
81
+ | Build the MVP | sign-in, an admin app, transactional email | `auth`, `admin`, `email` + a provider |
82
+ | Onboard teams | organizations, tenant isolation, roles | `teams`, `multitenant`, `rbac` |
83
+ | Charge money | subscriptions, plan limits, webhooks | `billing`, `billing-stripe`, `entitlements` |
84
+ | Scale the backend | jobs, caching, files, rate limits, API access | `queue`, `kv`, `storage`, `ratelimit`, `api-keys` |
85
+
86
+ Each row installs on top of the previous one. Nothing from a later row lands in your repo until you ask for it.
87
+
88
+ ## The stack
89
+
60
90
  | Concern | Choice |
61
91
  |---|---|
62
92
  | Marketing site (`apps/web`) | Astro on Workers static assets |
@@ -64,91 +94,47 @@ my-app/
64
94
  | Backend (`apps/api`) | Hono on Cloudflare Workers |
65
95
  | Database | Drizzle ORM on D1 (SQLite) or Postgres |
66
96
  | Auth | Better Auth |
97
+ | Billing | Stripe, or a console provider |
67
98
  | Email | Cloudflare Email Sending, Plunk, or a console logger |
99
+ | Storage | Cloudflare R2, or in memory |
68
100
  | Background work | Cloudflare Queues and Cron Triggers, or an in-process runner |
69
101
  | Infra | wrangler per workspace, or Pulumi via the `infra` module |
70
102
  | Monorepo | Turborepo + pnpm |
71
103
 
72
- ## Commands
73
-
74
- | Command | What it does |
75
- |---|---|
76
- | `init` | scaffold a new project (Astro landing + ui + config) |
77
- | `add` | apply a module into the current project, resolving `dependsOn` |
78
- | `env` | fill in the environment variables the installed modules declare (`--check` gates a deploy) |
79
- | `outdated` | report the base template and each installed module, current vs latest (`--check` gates CI) |
80
- | `update` | re-apply the base and modules at a newer version, with a merge plan for anything you edited |
81
- | `remove` | undo a module's applied files via the manifest, offline |
82
- | `list` | list the modules a registry offers, marking the ones installed here |
83
- | `new` | scaffold a new module in a registry repo (descriptor + files + skill stub) |
84
- | `doctor` | validate module descriptors, or a project's state files against each other |
85
-
86
- Every command answers `--help`. Flags, exit codes, coordinate grammar, and environment variables are in the [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md).
87
-
88
104
  ## Modules
89
105
 
90
- Modules come in tiers. A **capability** scaffolds a workspace and sets conventions. A **feature** drops files into those conventions. A **provider** supplies one implementation behind a capability's interface. A **driver** supplies the connection half of a stateful capability, and only one may be installed.
106
+ Modules come in tiers. A **capability** scaffolds a workspace and sets conventions. A **feature** drops files into those conventions. A **provider** supplies one implementation behind a capability's interface and is picked at runtime. A **driver** supplies the connection half of a stateful capability, and only one may be installed.
91
107
 
92
108
  | Tier | Modules |
93
109
  |---|---|
94
- | Capability | `api`, `database`, `validators`, `logger`, `auth`, `admin`, `email`, `sms`, `queue`, `kv`, `infra` |
95
- | Feature | `waitlist`, `teams`, `email-react`, `ratelimit`, `feature-flags` |
96
- | Provider | `email-console`, `email-cloudflare`, `email-plunk`, `logger-console`, `sms-console`, `queue-cloudflare`, `queue-memory`, `kv-cloudflare`, `kv-memory` |
110
+ | Capability | `api`, `database`, `validators`, `logger`, `auth`, `admin`, `email`, `sms`, `queue`, `kv`, `storage`, `billing`, `infra` |
111
+ | Feature | `waitlist`, `teams`, `multitenant`, `rbac`, `api-keys`, `entitlements`, `email-react`, `ratelimit`, `feature-flags` |
112
+ | Provider | `email-console`, `email-cloudflare`, `email-plunk`, `logger-console`, `sms-console`, `sms-khudebarta`, `queue-cloudflare`, `queue-memory`, `kv-cloudflare`, `kv-memory`, `storage-cloudflare`, `storage-memory`, `billing-console`, `billing-stripe` |
97
113
  | Driver | `database-d1`, `database-postgres` |
98
114
 
99
- `saasaloy add <name> --dry-run` prints what a module would do to your project before it does it. The one-table map of every module, what it gives you, and what it depends on is on the [Modules](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/modules.md) page.
115
+ What each module gives you and what it depends on is on the [Modules](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/modules.md) page. Which ones need a paid Cloudflare plan or a third-party account is in the [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md#email-providers). The short version: the base, `api`, `database-d1`, `auth`, `admin`, `waitlist` and `teams` run on the free tier, and every local provider runs with no account at all.
100
116
 
101
117
  The default registry is this repo. `saasaloy add waitlist` fetches `modules/waitlist/` from GitHub at a pinned commit SHA. Any repo with a `modules/` directory can serve as a registry with `saasaloy add owner/repo/<name>`. To publish your own, start at [Contribute a module](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/contribute-a-module.md).
102
118
 
103
- ## Cost and requirements
104
-
105
- `init`, `api`, `database` + `database-d1`, `validators`, `logger`, `auth`, `admin`, `waitlist`, and `teams` all run on Cloudflare's free tier. Cloudflare's limits are Cloudflare's to change, and a project that grows past them should expect to pay.
106
-
107
- A few modules need something the free tier does not cover:
108
-
109
- | Module | Needs |
110
- |---|---|
111
- | `email-cloudflare` | a Workers paid plan and a sending domain onboarded by hand in the Cloudflare dashboard |
112
- | `email-plunk` | a [Plunk](https://www.useplunk.com) account and `PLUNK_API_KEY` |
113
- | `database-postgres` | a Postgres server reachable from a Worker, with its URL in `DATABASE_URL`. Install instead of `database-d1`, never alongside |
114
- | `sms` | a third-party SMS account for any real send. Cloudflare has no SMS product. `sms-console` is free |
115
- | `queue-cloudflare` | a Workers paid plan, and the two queues created once with `wrangler queues create`. Install `queue-memory` instead for local work |
116
- | `kv-cloudflare` | a Workers KV namespace created with `wrangler kv namespace create`, and its id pasted into `wrangler.jsonc`. `kv-memory` needs nothing |
119
+ ## Commands
117
120
 
118
- The local providers (`email-console`, `sms-console`, `logger-console`, `queue-memory`, `kv-memory`) log or run inline instead of calling a service, so local development needs no plan, domain, or key. Details for each are in the [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md#email-providers).
121
+ `init`, `add`, `remove`, `update`, `outdated`, `env`, `list`, `new` and `doctor`. Every command answers `--help`. Flags, exit codes, the coordinate grammar and the project files are in the [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md).
119
122
 
120
123
  ## Deploy
121
124
 
122
- Each deployable workspace owns its `wrangler.jsonc` and `deploy` script. Run them one at a time, or install the `infra` module and deploy every Worker with one Pulumi program. See [Deploy to Cloudflare](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/deploy-to-cloudflare.md).
125
+ Each deployable workspace owns its `wrangler.jsonc` and `deploy` script, or the `infra` module deploys every Worker with one Pulumi program. See [Deploy to Cloudflare](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/deploy-to-cloudflare.md).
123
126
 
124
127
  ## Documentation
125
128
 
126
- All docs live in [`docs/wiki/`](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/index.md).
127
-
128
- **Use Saasaloy**
129
-
130
- - [Getting started](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/getting-started.md): install the CLI, scaffold a project, run it.
131
- - [Make the project yours](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/make-it-yours.md): the bundled skills for the product brief, landing copy, and theme.
132
- - [Modules](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/modules.md): every module in the default registry, in one table.
133
- - [Add a module](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/add-a-module.md): install a feature and its prerequisites.
134
- - [Remove a module](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/remove-a-module.md): take one back out, and what stays behind.
135
- - [Deploy to Cloudflare](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/deploy-to-cloudflare.md): ship each workspace.
136
-
137
- **Build a module**
138
-
139
- - [Contribute a module](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/contribute-a-module.md): authoring guides and how to test a module before it ships.
140
- - [A bad descriptor reached `main`](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/runbooks/bad-descriptor-on-main.md): the registry is live, so this is an incident.
129
+ Everything lives in [`docs/wiki/`](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/index.md). Start with [Getting started](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/getting-started.md), then [Modules](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/modules.md) and the [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md). [`CONTEXT.md`](https://github.com/mimukit/saasaloy/blob/main/CONTEXT.md) defines the vocabulary, and [`docs/adr/`](https://github.com/mimukit/saasaloy/blob/main/docs/adr/) records why the design is what it is, one decision per file.
141
130
 
142
- **Both tracks**
131
+ ## Status and roadmap
143
132
 
144
- - [Architecture](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/architecture.md): how the CLI, the registry, and a generated project fit together.
145
- - [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md): every command, flag, environment variable, and config file.
146
- - [`CONTEXT.md`](https://github.com/mimukit/saasaloy/blob/main/CONTEXT.md): the vocabulary. Module, capability, provider, coordinate, applier.
147
- - [`docs/adr/`](https://github.com/mimukit/saasaloy/blob/main/docs/adr/): why the design is what it is, one decision per file.
133
+ Saasaloy is pre-1.0 and under active development. Open work, planned modules and known gaps are tracked in the [issues](https://github.com/mimukit/saasaloy/issues). Breaking changes are called out in the [changelog](https://github.com/mimukit/saasaloy/blob/main/packages/cli/CHANGELOG.md).
148
134
 
149
135
  ## Contributing
150
136
 
151
- Issues and pull requests are welcome. [`CONTRIBUTING.md`](https://github.com/mimukit/saasaloy/blob/main/CONTRIBUTING.md) covers the `.dev/playground`, the lint and test gates, and the dependency update flow. The `billing` module is tracked in [#14](https://github.com/mimukit/saasaloy/issues/14).
137
+ Issues and pull requests are welcome. [`CONTRIBUTING.md`](https://github.com/mimukit/saasaloy/blob/main/CONTRIBUTING.md) covers the `.dev/playground`, the lint and test gates, and the dependency update flow.
152
138
 
153
139
  ## License
154
140
 
package/dist/index.js CHANGED
@@ -3881,7 +3881,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
3881
3881
  // package.json
3882
3882
  var package_default = {
3883
3883
  name: "saasaloy",
3884
- version: "0.3.0",
3884
+ version: "0.5.0",
3885
3885
  description: "Composable SaaS accelerator kit.",
3886
3886
  keywords: [
3887
3887
  "saas",