fabrica-e-commerce 0.2.3 → 0.2.4
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 +113 -78
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,122 +1,157 @@
|
|
|
1
1
|
# fabrica-e-commerce
|
|
2
2
|
|
|
3
|
-
Orange
|
|
3
|
+
Orange-themed NPX CLI for launching a Fabrica e-commerce storefront (Supabase + Vercel + Next.js) from any terminal — Windows, macOS, Linux, and Termux (no root required).
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Quick start
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
npx fabrica-e-commerce help
|
|
9
8
|
npx fabrica-e-commerce build
|
|
10
9
|
```
|
|
11
10
|
|
|
12
|
-
|
|
11
|
+
Or install globally:
|
|
13
12
|
|
|
14
13
|
```bash
|
|
15
14
|
npm install -g fabrica-e-commerce
|
|
16
15
|
fabrica build
|
|
17
16
|
```
|
|
18
17
|
|
|
18
|
+
Both `fabrica` and `fabrica-e-commerce` binaries are available after a global install.
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
---
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
## Commands
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
24
|
+
| Command | Description |
|
|
25
|
+
|---------|-------------|
|
|
26
|
+
| `build` | Full deploy wizard — Supabase → secrets → admin password → clone → Vercel or local |
|
|
27
|
+
| `list` | Show all projects and view details |
|
|
28
|
+
| `env` | Update environment variables for any project |
|
|
29
|
+
| `rerun` | Re-open or restart an existing project |
|
|
30
|
+
| `vins` | Verify and auto-install CLI dependencies (git, gh, vercel) |
|
|
31
|
+
| `clean` | Remove local data, env files, or logout from Vercel / GitHub |
|
|
32
|
+
| `info` | Package, bridge, repo, and storage info |
|
|
33
|
+
| `help` | Show the command guide |
|
|
30
34
|
|
|
31
|
-
|
|
35
|
+
---
|
|
32
36
|
|
|
33
|
-
|
|
34
|
-
npm run test:pack
|
|
35
|
-
```
|
|
37
|
+
## Build flow (6 steps)
|
|
36
38
|
|
|
37
|
-
|
|
39
|
+
### Step 1 — Dependency check
|
|
40
|
+
Verifies `git` is installed. Auto-installs it if missing.
|
|
38
41
|
|
|
39
|
-
|
|
42
|
+
### Step 2 — Supabase connect
|
|
43
|
+
Posts your schema/seed SQL to the Fabrica bridge (`sparrow-supabase-connect.lovable.app`), opens the OAuth connect URL in your browser, and polls until the Supabase project is provisioned and returns `{ url, anonKey }`.
|
|
44
|
+
|
|
45
|
+
### Step 3 — Environment variables
|
|
46
|
+
Prompts for your API keys:
|
|
47
|
+
|
|
48
|
+
| Variable | Purpose |
|
|
49
|
+
|----------|---------|
|
|
50
|
+
| `RAZORPAY_KEY_ID` | Razorpay payment key ID |
|
|
51
|
+
| `RAZORPAY_KEY_SECRET` | Razorpay payment secret |
|
|
52
|
+
| `OPENROUTER_API_KEY` | OpenRouter AI API key |
|
|
53
|
+
| `UMAMI_WEBSITE_ID` | Umami analytics website ID |
|
|
54
|
+
| `UMAMI_API_KEY` | Umami analytics API key |
|
|
55
|
+
| `SHIPPO_API_KEY` | Shippo shipping API key |
|
|
56
|
+
|
|
57
|
+
`SUPABASE_URL` and `SUPABASE_ANON_KEY` are filled automatically from the bridge response.
|
|
58
|
+
|
|
59
|
+
### Step 4 — Admin password
|
|
60
|
+
Prompts for a password to protect your store's admin and edit panel. Stored as the `PASS` environment variable.
|
|
61
|
+
|
|
62
|
+
### Step 5 — Clone storefront
|
|
63
|
+
Clones `https://github.com/trucount/fabrica-final-e-c.git` into a local builds directory. Asks for a project name (used as the Vercel project name).
|
|
64
|
+
|
|
65
|
+
### Step 6 — Deploy target
|
|
66
|
+
Choose how to run your store:
|
|
67
|
+
|
|
68
|
+
**Local mode**
|
|
69
|
+
- Writes all collected variables to `.env.local` inside the cloned app.
|
|
70
|
+
- Runs `pnpm install` (or `npm install`) and starts the Next.js dev server at `http://localhost:3000`.
|
|
40
71
|
|
|
41
|
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
- `OPENROUTER_API_KEY`
|
|
55
|
-
- `UMAMI_WEBSITE_ID`
|
|
56
|
-
- `UMAMI_API_KEY`
|
|
57
|
-
- `SHIPPO_API_KEY`
|
|
58
|
-
4. Adds hardcoded values requested by the project:
|
|
59
|
-
- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=0000`
|
|
60
|
-
- `UMAMI_API_CLIENT_ENDPOINT=https://api.umami.is/v1`
|
|
61
|
-
- `SUPABASE_SERVICE_ROLE_KEY=0000`
|
|
62
|
-
5. Adds `SUPABASE_URL` and `SUPABASE_ANON_KEY` from the bridge response.
|
|
63
|
-
6. **Step 3 — run target:**
|
|
64
|
-
- Asks whether to run the storefront **locally** or deploy on **Vercel cloud**.
|
|
65
|
-
- Local mode writes every collected variable to `.env.local` inside the cloned Next.js app, installs dependencies (`pnpm install` when available, otherwise `npm install`), and starts `pnpm run dev`/`npm run dev` at `http://localhost:3000`.
|
|
66
|
-
- Vercel mode verifies you're logged in to Vercel (`vercel whoami`); if not, runs an interactive `vercel login` and waits for it to finish.
|
|
67
|
-
- Vercel mode logs in to the GitHub CLI if needed (`gh auth login`) and creates a user-owned repo from the hardcoded storefront source with a fork/template flow, avoiding local `git push` credentials.
|
|
68
|
-
- Vercel mode links a new Vercel project with `vercel link --yes --project <name>` and connects it to the new GitHub repo with `vercel git connect` so future pushes auto-deploy.
|
|
69
|
-
- Vercel mode writes every collected environment variable (including the Supabase URL/anon key) to the **production, preview, and development** environments with `vercel env add`, so the values are permanent for the project, not just the first deploy.
|
|
70
|
-
- Vercel mode creates the production deployment with `vercel --prod --yes`.
|
|
71
|
-
|
|
72
|
-
## Dependency check (`vins`)
|
|
73
|
-
|
|
74
|
-
Run `npx fabrica-e-commerce vins` any time to verify the tools the CLI depends on:
|
|
72
|
+
**Vercel cloud mode**
|
|
73
|
+
- Checks and installs `gh` (GitHub CLI) and `vercel` CLI if missing.
|
|
74
|
+
- Logs in to Vercel interactively if needed.
|
|
75
|
+
- Logs in to GitHub CLI if needed and forks the storefront to a new user-owned repo.
|
|
76
|
+
- Links a new Vercel project and connects it to the GitHub repo for auto-deploys.
|
|
77
|
+
- Writes every environment variable to **production, preview, and development** environments with `vercel env add`.
|
|
78
|
+
- Deploys with `vercel --prod`.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Dependency installer (`vins`)
|
|
83
|
+
|
|
84
|
+
`vins` checks for `git`, `gh`, and the Vercel CLI and auto-installs anything missing — **no root or admin required** on any platform.
|
|
75
85
|
|
|
76
86
|
```bash
|
|
77
87
|
npx fabrica-e-commerce vins
|
|
78
88
|
```
|
|
79
89
|
|
|
80
|
-
|
|
90
|
+
| Platform | Install strategy |
|
|
91
|
+
|----------|-----------------|
|
|
92
|
+
| **Termux** | `pkg install` — no root needed |
|
|
93
|
+
| **Linux (no root)** | Homebrew/Linuxbrew → system pkg manager (tries without sudo first) → conda/mamba → binary download from GitHub releases |
|
|
94
|
+
| **Linux (with sudo)** | apt-get / dnf / yum / pacman / zypper / apk |
|
|
95
|
+
| **macOS** | `brew install` → auto-installs Homebrew if missing → binary download |
|
|
96
|
+
| **Windows (no admin)** | `winget --scope user` → auto-installs Scoop → `scoop install` → Chocolatey |
|
|
81
97
|
|
|
98
|
+
If a tool still can't be installed automatically, `vins` prints the correct manual install command for your platform and exits with a non-zero status.
|
|
82
99
|
|
|
100
|
+
---
|
|
83
101
|
|
|
84
|
-
##
|
|
102
|
+
## Managing projects
|
|
85
103
|
|
|
86
|
-
|
|
104
|
+
### `list`
|
|
105
|
+
Shows all projects saved locally with their type (local/cloud), creation date, GitHub repo, Supabase URL, and live URL.
|
|
87
106
|
|
|
88
|
-
|
|
107
|
+
### `env`
|
|
108
|
+
Lets you update any environment variable for a saved project. For local projects it rewrites `.env.local`. For cloud projects it updates Vercel (production, preview, development) and triggers a redeploy.
|
|
89
109
|
|
|
90
|
-
|
|
110
|
+
### `rerun`
|
|
111
|
+
- **Local projects** — restarts the dev server at `http://localhost:3000`.
|
|
112
|
+
- **Cloud projects** — opens the production URL in your browser.
|
|
91
113
|
|
|
92
|
-
|
|
114
|
+
### `clean`
|
|
115
|
+
Offers four modes: delete local project records, wipe env files, logout from Vercel, logout from GitHub, or a full reset of all of the above.
|
|
93
116
|
|
|
94
|
-
|
|
95
|
-
2. In GitHub, open **Settings → Secrets and variables → Actions**.
|
|
96
|
-
3. Add a repository secret named `NPM_TOKEN` with that npm token.
|
|
117
|
+
---
|
|
97
118
|
|
|
98
|
-
|
|
119
|
+
## Local project records
|
|
99
120
|
|
|
100
|
-
|
|
101
|
-
2. Runs `npm run test:cli`.
|
|
102
|
-
3. Runs `npm run test:pack`.
|
|
103
|
-
4. Checks the current latest version on npm and bumps `package.json` to the next patch version when needed.
|
|
104
|
-
5. Runs `npm publish --access public --provenance`.
|
|
105
|
-
6. Commits the published version back to GitHub with `[skip npm-publish]` to avoid an infinite publish loop.
|
|
121
|
+
Deployment metadata is saved to `~/.fabrica-ecommerce/projects.json`. Secret values are **not** stored — only variable names, project path, repo URL, creation date, and Supabase URL are recorded.
|
|
106
122
|
|
|
107
|
-
|
|
123
|
+
---
|
|
108
124
|
|
|
125
|
+
## Requirements
|
|
109
126
|
|
|
110
|
-
|
|
127
|
+
- **Node.js 18.17+**
|
|
128
|
+
- **Git** — run `npx fabrica-e-commerce vins` to auto-install
|
|
129
|
+
- **GitHub CLI (`gh`)** — run `vins` to auto-install; interactive login handled by `build`
|
|
130
|
+
- **Vercel account** — login is handled interactively by `build` if needed
|
|
131
|
+
- A **Supabase** account connected via the Fabrica bridge
|
|
111
132
|
|
|
112
|
-
|
|
133
|
+
---
|
|
113
134
|
|
|
114
|
-
|
|
135
|
+
## Automatic npm publishing (GitHub Actions)
|
|
115
136
|
|
|
116
|
-
|
|
137
|
+
The workflow at `.github/workflows/npm-publish.yml` verifies and publishes to npm on every push to `main`, `master`, or `work`, and can be triggered manually from the Actions tab.
|
|
138
|
+
|
|
139
|
+
**Setup — add your npm token once:**
|
|
140
|
+
1. Create an npm token with publish permissions.
|
|
141
|
+
2. In GitHub go to **Settings → Secrets and variables → Actions**.
|
|
142
|
+
3. Add a secret named `NPM_TOKEN`.
|
|
143
|
+
|
|
144
|
+
**What the workflow does on each run:**
|
|
145
|
+
1. Upgrades npm to the latest version (avoids bundled-npm bugs on GitHub runners).
|
|
146
|
+
2. Runs `npm install`, `npm run build`, `npm run test:cli`, `npm run test:pack`.
|
|
147
|
+
3. Bumps `package.json` to the next patch version if the current version is already published.
|
|
148
|
+
4. Publishes with `npm publish --access public --provenance`.
|
|
149
|
+
5. Commits the bumped version back to GitHub with `[skip npm-publish]` to prevent an infinite loop.
|
|
150
|
+
|
|
151
|
+
> The `repository.url` in `package.json` must match the GitHub repo used by the workflow — npm uses it to verify the provenance bundle.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Windows notes
|
|
117
156
|
|
|
118
|
-
|
|
119
|
-
- Git installed and available in PATH
|
|
120
|
-
- [GitHub CLI](https://github.com/cli/cli) (`gh`) installed and available in PATH — used to create the new repository and push the storefront code. Logging in (`gh auth login`) is handled interactively by `build` if needed.
|
|
121
|
-
- A Vercel account. The Vercel CLI will prompt/login when required (`build` also runs this check up front).
|
|
122
|
-
- Run `npx fabrica-e-commerce vins` to check for and auto-install `git`/`gh` if either is missing.
|
|
157
|
+
The CLI spawns npm commands through `npx.cmd` on Windows so `npx vercel@latest ...` works correctly from CMD and PowerShell. If you see a Vercel login prompt, complete it in your browser and the CLI will continue automatically.
|
package/package.json
CHANGED