templates

Name: templates
Author: butterbase-ai

533stars40forks

How to install templates?

butterbase-ai/butterbase-skills/templates

$npx -y skills add butterbase-ai/butterbase-skills --skill templates

Installs into the current project.

Summary

Use when publishing a Butterbase app as a public template (visibility + listed + repo snapshot), browsing the template gallery, or cloning a template with environment-variable preflight. Templates are public apps with a pushed repo snapshot that other users can fork into their ow

Files · 1

View on GitHub

SKILL.md

1	# Butterbase Templates
2
3	A "template" is a Butterbase app marked `visibility: 'public'` and `listed: true`, with a repo snapshot uploaded via `butterbase repo push`. The clone pipeline replays the source app's schema, RLS, functions, config, and frontend artifact into a new app in the cloner's region; the pushed repo gives the cloner the actual source tree to keep developing.
4
5	## How the repo snapshot flows (`repo push` / `repo pull` / `repo status`)
6
7	The repo snapshot is the source-code half of a template; the clone job replays schema/RLS/functions/config separately. Both halves are pinned via `apps.repo_latest_snapshot`.
8
9	- `butterbase repo init <app_id>` — Bind the current directory to an app. Writes `.butterbase/config.json` and seeds `.butterbaseignore`. Run once per project. `butterbase clone` does this for you on the cloner side.
10	- `butterbase repo push -m "<msg>"` — Publisher uploads. Walks the project tree (respecting `.butterbaseignore` + `.gitignore`), hashes files (SHA256), uploads any new blobs via presigned URLs, commits a new immutable snapshot, updates the local pin. Content-addressed — re-pushing an unchanged tree is a no-op upload. This is the only way the source tree gets onto the snapshot. Clone replay does not synthesise it.
11	- `butterbase repo pull [--force]` — Cloner / collaborator downloads. Fetches the remote latest manifest, diffs against the locally pinned snapshot, downloads changed/new files, deletes files that are gone upstream, and bumps the local pin. Refuses if a file was deleted upstream but modified locally — `--force` overrides. `butterbase clone` invokes this automatically after the clone job completes, so cloners get a working tree without thinking about it.
12	- `butterbase repo status` — Inspector. Shows files modified vs pinned, untracked locally, and deleted locally. Use before `push` to confirm what's about to be uploaded; use after `pull` to confirm a clean tree.
13	- `butterbase repo log` — List all snapshots for the bound app.
14	- `butterbase repo wipe` — Destructive; clear all snapshots. Requires app-id confirmation.
15
16	Reading a template's source code: clone it into a scratch directory — `butterbase clone <source_app_id> /tmp/peek` — and read the resulting tree. There is no separate "browse template source" CLI; snapshots are only materialised by `repo pull`, which requires the caller to be bound to the app.
17
18	Updating a clone with newer template versions: clones don't auto-follow the source — each clone owns its own app and its own snapshot history. `butterbase repo pull` in the clone fetches the cloner's own latest, not the upstream publisher's. To track upstream changes, the cloner has to clone again into a sibling directory and merge with git, or the publisher has to push to a snapshot the clone can read (uncommon).
19
20	## What clone replay DOES and DOES NOT copy
21
22	\| Copied on clone \| Not copied — cloner must do \|
23	\|---\|---\|
24	\| Schema (DDL) \| App user data (unless explicitly seeded) \|
25	\| RLS policies \| Auth provider OAuth secrets \|
26	\| Functions (handlers + non-secret env) \| Function secrets / API keys (cloner provides via preflight) \|
27	\| App config \| Agents (record in `agents` table) — bundle as `agents/*.json` in the repo and re-import after clone \|
28	\| Frontend artifact (with app-id rewritten) \| Storage objects (only the bucket config replays) \|
29	\| Repo snapshot (files) \| OAuth integration installs \|
30
31	This makes the README in the pushed repo the most important publishing artifact — it has to explain everything that doesn't replay.
32
33	## When to use
34
35	- Publishing an app you built as a public template.
36	- Listing or searching templates.
37	- Cloning a template (or guiding a user through clone with env-var preflight).
38	- Toggling visibility / listed status on an existing app.
39
40	## Publishing checklist
41
42	Before flipping `visibility: public`, verify all of the following. Each one prevents a class of broken-on-clone bugs.
43
44	1. Repo snapshot exists and is fresh. Run `butterbase repo push -m "publish v1"` from the project root. Confirm `apps.repo_latest_snapshot` is non-null via `manage_app action: get`. The clone preflight endpoint returns `has_repo: false` if missing, and discovery hides templates without a repo for several sort modes.
45
46	2. README.md at repo root with clone instructions. No formal "template instructions" field exists — the README in the pushed snapshot is the instructions. It MUST cover:
47	- One-line pitch (what does this app do?)
48	- Required env vars per function — the preflight surfaces keys but not what they're for. List each (e.g., `STRIPE_SECRET_KEY — server-side Strip

People who liked this also viewed

6 picks

Type

templates

533stars40forks

View on GitHub

How to install templates?

butterbase-ai/butterbase-skills/templates

$npx -y skills add butterbase-ai/butterbase-skills --skill templates

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Butterbase Templates
2
3	A "template" is a Butterbase app marked `visibility: 'public'` and `listed: true`, with a repo snapshot uploaded via `butterbase repo push`. The clone pipeline replays the source app's schema, RLS, functions, config, and frontend artifact into a new app in the cloner's region; the pushed repo gives the cloner the actual source tree to keep developing.
4
5	## How the repo snapshot flows (`repo push` / `repo pull` / `repo status`)
6
7	The repo snapshot is the source-code half of a template; the clone job replays schema/RLS/functions/config separately. Both halves are pinned via `apps.repo_latest_snapshot`.
8
9	- `butterbase repo init <app_id>` — Bind the current directory to an app. Writes `.butterbase/config.json` and seeds `.butterbaseignore`. Run once per project. `butterbase clone` does this for you on the cloner side.
10	- `butterbase repo push -m "<msg>"` — Publisher uploads. Walks the project tree (respecting `.butterbaseignore` + `.gitignore`), hashes files (SHA256), uploads any new blobs via presigned URLs, commits a new immutable snapshot, updates the local pin. Content-addressed — re-pushing an unchanged tree is a no-op upload. This is the only way the source tree gets onto the snapshot. Clone replay does not synthesise it.
11	- `butterbase repo pull [--force]` — Cloner / collaborator downloads. Fetches the remote latest manifest, diffs against the locally pinned snapshot, downloads changed/new files, deletes files that are gone upstream, and bumps the local pin. Refuses if a file was deleted upstream but modified locally — `--force` overrides. `butterbase clone` invokes this automatically after the clone job completes, so cloners get a working tree without thinking about it.
12	- `butterbase repo status` — Inspector. Shows files modified vs pinned, untracked locally, and deleted locally. Use before `push` to confirm what's about to be uploaded; use after `pull` to confirm a clean tree.
13	- `butterbase repo log` — List all snapshots for the bound app.
14	- `butterbase repo wipe` — Destructive; clear all snapshots. Requires app-id confirmation.
15
16	Reading a template's source code: clone it into a scratch directory — `butterbase clone <source_app_id> /tmp/peek` — and read the resulting tree. There is no separate "browse template source" CLI; snapshots are only materialised by `repo pull`, which requires the caller to be bound to the app.
17
18	Updating a clone with newer template versions: clones don't auto-follow the source — each clone owns its own app and its own snapshot history. `butterbase repo pull` in the clone fetches the cloner's own latest, not the upstream publisher's. To track upstream changes, the cloner has to clone again into a sibling directory and merge with git, or the publisher has to push to a snapshot the clone can read (uncommon).
19
20	## What clone replay DOES and DOES NOT copy
21
22	\| Copied on clone \| Not copied — cloner must do \|
23	\|---\|---\|
24	\| Schema (DDL) \| App user data (unless explicitly seeded) \|
25	\| RLS policies \| Auth provider OAuth secrets \|
26	\| Functions (handlers + non-secret env) \| Function secrets / API keys (cloner provides via preflight) \|
27	\| App config \| Agents (record in `agents` table) — bundle as `agents/*.json` in the repo and re-import after clone \|
28	\| Frontend artifact (with app-id rewritten) \| Storage objects (only the bucket config replays) \|
29	\| Repo snapshot (files) \| OAuth integration installs \|
30
31	This makes the README in the pushed repo the most important publishing artifact — it has to explain everything that doesn't replay.
32
33	## When to use
34
35	- Publishing an app you built as a public template.
36	- Listing or searching templates.
37	- Cloning a template (or guiding a user through clone with env-var preflight).
38	- Toggling visibility / listed status on an existing app.
39
40	## Publishing checklist
41
42	Before flipping `visibility: public`, verify all of the following. Each one prevents a class of broken-on-clone bugs.
43
44	1. Repo snapshot exists and is fresh. Run `butterbase repo push -m "publish v1"` from the project root. Confirm `apps.repo_latest_snapshot` is non-null via `manage_app action: get`. The clone preflight endpoint returns `has_repo: false` if missing, and discovery hides templates without a repo for several sort modes.
45
46	2. README.md at repo root with clone instructions. No formal "template instructions" field exists — the README in the pushed snapshot is the instructions. It MUST cover:
47	- One-line pitch (what does this app do?)
48	- Required env vars per function — the preflight surfaces keys but not what they're for. List each (e.g., `STRIPE_SECRET_KEY — server-side Strip

People who liked this also viewed

6 picks

Type