Skip to content
Skills Library
Programming · Building & coding

app-dev-practices

/app-dev-practices

Practical guide for building Fusebase Apps apps. Use when: (1) Creating a new app, (2) Setting up project structure, Vite config, or authentication, (3) Building or registering apps, (4) Configuring permissions or public access, (5) Navigating between apps, (6) Fetching user details, (7) Troubleshooting build issues.

Licence
MIT
Last repository change
25.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
2
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 25.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Practical guide for building Fusebase Apps apps. Use when: (1) Creating a new app, (2) Setting up project structure, Vite config, or authentication, (3) Building or registering apps, (4) Configuring permissions or public access, (5) Navigating between apps, (6) Fetching user details, (7) Troubleshooting build issues.

Original author description

Practical guide for building Fusebase Apps apps. Use when: (1) Creating a new app, (2) Setting up project structure, Vite config, or authentication, (3) Building or registering apps, (4) Configuring permissions or public access, (5) Navigating between apps, (6) Fetching user details, (7) Troubleshooting build issues.

How it works

  1. Always Scaffold First
  2. Multi-User by Default
  3. Project Structure
  4. Consuming Another Fusebase App's API
  5. Authentication
  6. User Details
  7. Navigation
  8. UI Framework
  9. Building Apps
  10. Registering Apps
Original SKILL.md headings · 236 lines, 1,451 words
SKILL.md preview
---
name: app-dev-practices
description: "Practical guide for building Fusebase Apps apps. Use when: (1) Creating a new app, (2) Setting up project structure, Vite config, or authentication, (3) Building or registering apps, (4) Configuring permissions or public access, (5) Navigating between apps, (6) Fetching user details, (7) Troubleshooting build issues."
---

# App Dev Practices

## Always Scaffold First

Run `fusebase scaffold --template spa --dir apps/<name>` before writing any app files. This generates the canonical React + Vite + Tailwind v4 + shadcn/ui project structure. For apps needing a backend, also run `fusebase scaffold --template backend --dir apps/<name>`. Customize from there — never recreate boilerplate by hand.

## Multi-User by Default

**Every app is multi-user.** Multiple users access the same deployed app simultaneously, each with their own identity (app token). Never design for a single user.

**Rules:**
- **Per-user state** (OAuth tokens, preferences, selections) must be stored **per-user** — use httpOnly cookies (set by the server, scoped to the user's browser) or dashboard rows keyed by user ID
- **Shared env vars / Fusebase secrets** are global — they are the **same for all users**. Never use them for per-user credentials or settings
- **In-memory backend variables** are shared across all requests from all users — never store per-user data in module-level variables
- When integrating third-party APIs with OAuth, each user must go through their own auth flow and get their own tokens

- **Stable partition keys only:** when storing per-user rows, the partition key must come from a **stable identity** (`userId`, `orgUserId`, email if immutable), not from session/token artifacts.
- **Never use token-derived keys** (e.g. `ft:*`, JWT fragments, rotating session IDs) as persistent `user_key`/partition keys — they change between sessions and split one user's data into multiple buckets.
- **Recommended format:** normalize once in backend (`user:<userId>`) and reuse the same key for both read and write paths.

**Ask yourself:** "If two users open this app at the same time, will they interfere with each other?" If yes, the design is wrong.

## Project Structure

Apps are React/Vite apps in `apps/`:

```
apps/
  my-app/
    package.json
    vite.config.ts
    src/
      App.tsx
      main.tsx
```

Use existing apps in `apps/` as reference when building new ones.

### Vite Config: Ignore Logs Directory

`fusebase dev start` writes debug logs to `<app-dir>/logs/`. Tell Vite's file watcher to ignore this directory so it doesn't trigger unnecessary reloads:

```ts
// vite.config.ts
export default defineConfig({
  server: {
    watch: {
      ignored: ['**/logs/**'],
    },
  },
  // ...rest of config
});
```

**Always include this in every app's `vite.config.ts`.**

### Vite Config: Do NOT add inline `css.postcss`

Do **NOT** add a `css.postcss` block in `vite.config.ts`. An inline `css` config — even with an empty `plugins` array — **overrides** the external `postcss.config.js` entirely, silently disabling Tailwind and all other PostCSS plugins.

```ts
// ❌ BROKEN — overrides postcss.config.js, Tailwind never runs
export default defineConfig({
  css: {
    postcss: {
      plugins: [],
    },
  },
});
```

```ts
// ✅ CORRECT — no css.postcss block; Vite picks up postcss.config.js automatically
export default defineConfig({
  plugins: [react()],
  // ...rest of config
});
```

PostCSS plugins (`@tailwindcss/postcss`, `autoprefixer`) belong in `postcss.config.js` only.

### Backend (Optional)

Apps may optionally include a `backend/` subfolder for a backend API (REST + WebSockets). **Do not add a backend unless the app genuinely needs backend logic** — most apps work fine with the Dashboard SDK alone. See skill **app-backend** for when and how to add one. The backend is served at `/api`.

<!-- CUSTOM:SKILL:BEGIN -->
## Consuming Another Fusebase App's API

If your app needs to integrate with **another Fusebase app in the same organization**, do **not** treat that app as an external opaque service by default.

Use this workflow:

1. Discover the target app's published API through Gate:
   - `searchAppApiOperations`
   - `listAppApiOperations`
   - `getAppApiOperation`
2. Inventory the relevant operations and their request or response shapes.
3. Build the integration against that published contract.
4. Use `callAppApi` or direct runtime probing only if behavior still needs live verification.

Avoid these dead ends as a first move:

- searching for the target app's source code in the current repo
- asking for raw OpenAPI export or manual endpoint lists
- spelunking dashboard tables or storage schemas instead of using the published app API

If a published app API exists, it is the primary cross-app integration surface.

For security-sensitive operations, prefer contract-level app API policy:

- `x-fusebase-allowed-callers` restricts the caller identity: a caller id is the calling project's `productId`, e.g. `client:<productId>`, not an app id — sibling apps of one project share it.
- `x-fusebase-required-permissions` restricts caller capability and must use the app API namespace `app_api.<namespace>.<capability>.<action>`, e.g. `app_api.client_portal.provision.write`.
- Do not use built-in Gate permissions such as `isolated_store.read` for app-to-app operation authorization.
- **Enforcement arrives per environment.** Both extensions are published to the registry and read by `callAppApi`, but enforcement is switched on per environment by the platform. Declare them now and grant the matching capability to caller apps with `fusebase app update <callerAppId> --permissions "app_api.<namespace>.<capability>.<action>"`, so the grants are in place when enforcement reaches yours. Never rely on them as your only authorization check today.
<!-- CUSTOM:SKILL:END -->



## Authentication

Apps run as the main window. The platform sets a `fbsfeaturetoken` cookie automatically.

**Startup flow:**

1. Read app token on app load: check `fbsfeaturetoken` cookie first, fall back to `window.FBS_FEATURE_TOKEN` if the cookie is absent
2. Render app once token is available (show loading state until then)
3. Pass token via `x-app-feature-token` for direct SDK / Fusebase proxy calls
4. For calls to the app's own backend (`/api/*`), rely on the same-origin cookie and make backend handlers read `x-app-feature-token` or fallback to `fbsfeaturetoken`

**All apps MUST handle token expiration** (`AppTokenValidationError` / 401). See skill **handling-authentication-errors** for the implementation pattern.

### Backend session apps (httpOnly cookie)

If the app has a **backend** and the SPA boots auth from **`GET /api/account/me`** (or similar) with `credentials: 'include'`:

- Load **handling-authentication-errors** § **session probe invariant** before writing auth bootstrap code.
- **401 only** → login screen. **502/5xx/network** → retry with deploy tolerance, then transient error — **never** `setState('anon')` on proxy errors.
- **`fusebase deploy` restarts the backend** — session probe must survive the rollout window (see skill for retry delays).

Do not conflate this with platform `fbsfeaturetoken` expiry (`AppTokenValidationError` modal) — they are separate layers.

## User Details

Fetch current user:

```typescript
const response = await fetch('https://app-api.thefusebase.com/v4/api/users/me', {
  headers: { 'x-app-feature-token': appToken },
})
const user = response.ok ? await response.json() : null
// authenticated: { id: 4124, email: "testemail@gmail.com" }
// anonymous visitor on a public app: null
```

Important for public apps:

- A visitor app token may be valid even when `/users/me` returns 401
- In that case, treat the result as `user: null`, not as "session expired"
- Show the login/auth form for anonymous visitors
- Only show a "Session Expired" modal for actual `AppTokenValidationError` flows

See skill **handling-authentication-errors** for the exact 401 handling rules.

## Navigation

Use standard browser navigation (React Router, etc.) since apps run as the main window. For routing setup, see skill **app-routing**.

## UI Framework

Use **shadcn/ui**. For design and UX guidance (layout, tokens, components, accessibility), see skill **app-ui-design**.

## Building Apps

```bash
cd apps/my-app
npm run build
```

### devDependencies Missing

If `npm run build` fails because vite/typescript are not found, npm may be running in production mode (`NODE_ENV=production` — common in VS Code / Claude Code). Fix:

```bash
npm install --include=dev
```

### Typecheck at project root

From the repo root, `npm run typecheck` runs `tsc` for each app (see root `package.json`). It catches strict TypeScript issues that ESLint does not, including the same failures as `tsc` inside `fusebase deploy`’s build. Claude Code Stop hooks run it after lint.

## Registering Apps

After creating an app, register it via `fusebase app create` from the project root:

```bash
fusebase app create --name <name> --subdomain <subdomain> --path <path> --dev-command <command> --build-command <command> --output-dir <dir>
```

**Execute this command automatically** after writing the app code — do not ask the user to run it manually.

### Access Principals

Use `--access` to control who can access the app. Principals are comma-separated:

```bash
# Public (visitor) access
fusebase app create --name <name> --access=visitor
fusebase app update <appId> --access=visitor

# Org role access (guest, client, member, manager, owner)
fusebase app update <appId> --access=orgRole:member
fusebase app update <appId> --access=orgRole:member,orgRole:client

# Combine visitor and org roles
fusebase app update <appId> --access=visitor,orgRole:member
```

### Permissions

Use `--permissions` with `fusebase app create` when the app is first registered. Only use `fusebase app update --permissions` when changing permissions on an already-registered app. Use MCP to discover dashboard/view IDs. See skill **fusebase-cli** for permission format and examples.

## Getting App URLs

```bash
fusebase app list
```

Lists all apps with their deployed URLs. Use this to get actual URLs — do NOT hardcode or guess them.

**Always use the full subdomain URL** (read `FUSEBASE_APP_HOST` from `.env`, e.g. `https://my-app.thefusebase.app/`), never relative paths. Each app is served from its own subdomain root — see skill **app-routing**.

## Cross-App Navigation

Use standard browser navigation (`<a>`, `window.location`) with full app URLs obtained from `fusebase app list`.

Versions

RepositoryScoreLicence
This page · ryan-haver/fusebase-mcp100MIT
fusebase-dev/fusebase-flow100MIT

Database snapshot: 13.11.2026 · package version 1f896a551ec6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95fusebase-cli
    Complete guide for using the Fusebase CLI (fusebase) tool to initialize, develop, and deploy Fusebase Apps apps. Use when: 1. Initializing new Fusebase Apps projects, 2. Creating or configuring apps, 3. Running apps locally or deploying them 4. Setting up app permissions for dashboards.
  • 95fusebase-cli
    Complete guide for using the Fusebase CLI (fusebase) tool to initialize, develop, and deploy Fusebase Apps apps. Use when: 1. Initializing new Fusebase Apps projects, 2. Creating or configuring apps, 3. Running apps locally or deploying them 4. Setting up app permissions for dashboards.
  • 100app-routing
    Guide for implementing client-side routing in Fusebase Apps apps. Use when: 1. Adding routing (React Router) to an app, 2. Fixing broken routes or 404s after deployment, 3. Configuring the router.
  • 100app-routing
    Guide for implementing client-side routing in Fusebase Apps apps. Use when: 1. Adding routing (React Router) to an app, 2. Fixing broken routes or 404s after deployment, 3. Configuring the router.
  • 100create-app
    Creates managed apps using React and Vite. Use when scaffolding a new app with `ms app create` and ending on local dev with `ms app dev`.
  • 100create-app
    Creates apps on Copilot Managed Runtime using React and Vite. Use when scaffolding a new app with `ms app create` and ending on local dev with `ms app dev`.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.