/fireact-builder

name: fireact-builder
description: Helps customize and extend Fireact SaaS apps after installation. Auto-detects Fireact projects by checking for @fireact.dev/app in package.json. Invoke when the user wants to add features, pages, custom components, navigation, branding, Cloud Functions, or i18n.
user_invocable: true

Fireact Builder — Post-Installation Customization Skill

You help developers customize and extend their Fireact SaaS apps via natural language. This skill covers adding pages, replacing components, customizing navigation, branding, Cloud Functions, Firestore collections, and i18n.

---

1. Project Detection

Before doing anything, confirm this is a Fireact project:

1. Check `package.json` for `@fireact.dev/app` in dependencies 2. Check `src/config/app.config.json` exists 3. Check `src/App.tsx` imports from `@fireact.dev/app`

If any check fails, tell the user this doesn't appear to be a Fireact project and suggest running `npx create-fireact-app` first.

---

2. State Reading Protocol

**MUST read these files before making any changes** to understand the current project state:

| File | What to learn | |------|---------------| | `src/App.tsx` | Current routing, imports, which components are local vs from `@fireact.dev/app` | | `src/config/app.config.json` | Route paths, permissions, settings | | `src/config/stripe.config.json` | Subscription plans | | `src/i18n/en.ts` | Existing translation keys | | `src/components/` (list files) | Existing custom components | | `functions/src/index.ts` | Existing Cloud Functions | | `firestore.rules` | Existing security rules |

---

3. Customization Playbooks

A. Add New Subscription Page

Use when the user wants a page scoped to a subscription (e.g., "add a reports page", "add an analytics page").

**Steps:**

1. **Create component** at `src/components/<PageName>.tsx`:

• Import `useSubscription`, `useConfig`, `useTranslation` from `@fireact.dev/app`
• Handle loading state (spinner) and error state (redirect to home)
• Use TailwindCSS for styling — no inline styles
• See `references/component-patterns.md` for template

2. **Add route key** to `src/config/app.config.json` under `pages`:

   "<pageName>": "/subscription/:id/<slug>"

3. **Add route** in `src/App.tsx` inside the `SubscriptionProvider > SubscriptionLayout` route block:

   <Route path={appConfig.pages.<pageName>} element={
     <ProtectedSubscriptionRoute requiredPermissions={['access']}>
       <PageName />
     </ProtectedSubscriptionRoute>
   } />

4. **Add import** at top of `src/App.tsx`:

   import PageName from './components/PageName';

5. **Add i18n keys** to `src/i18n/en.ts` (and other language files)

6. **Optionally** add to navigation menu (see Playbook E)

B. Add New Authenticated Page

Use when the user wants a page that requires login but is not scoped to a subscription (e.g., "add an API keys page", "add a settings page").

**Steps:**

1. **Create component** at `src/components/<PageName>.tsx`:

• Import `useAuth`, `useConfig` from `@fireact.dev/app`
• See `references/component-patterns.md` for template

2. **Add route key** to `src/config/app.config.json` under `pages`:

   "<pageName>": "/<slug>"

3. **Add route** inside `AuthenticatedLayout` block in `src/App.tsx`:

   <Route path={appConfig.pages.<pageName>} element={<PageName />} />

4. **Add import and translations**

C. Add New Public Page

Use when the user wants a page that doesn't require login (e.g., "add a landing page", "add a pricing page").

**Steps:**

1. **Create component** at `src/components/<PageName>.tsx`

2. **Add route** inside `PublicLayout` block in `src/App.tsx`:

   <Route path="/<slug>" element={<PageName />} />

3. **Add translations**

D. Replace/Customize Existing Component

Use when the user wants to change an existing component from `@fireact.dev/app` (e.g., "customize the sign-in page", "change the dashboard").

**Steps:**

1. **Identify** which `@fireact.dev/app` component to replace (see `references/component-patterns.md` for the full export list)

2. **Create local version** at `src/components/<ComponentName>.tsx` maintaining the same hook/context contract as the original

3. **Change import in `src/App.tsx`**:

• Remove the component from the `@fireact.dev/app` destructured import
• Add a local import:

     import ComponentName from './components/ComponentName';

4. **Reference** `references/component-patterns.md` for the expected patterns of each component type

E. Customize Navigation

Use when the user wants to add, remove, or reorder navigation items.

**Steps:**

1. **Create custom menu components** (e.g., `src/components/CustomSubscriptionDesktopMenu.tsx` and `CustomSubscriptionMobileMenu.tsx`)

2. **Follow the pattern**: `useLocation`, `useTranslation`, `useSubscription`, `useConfig`, `hasPermission()`

3. **Path replacement**: use `.replace(':id', subscription?.id || '')` for subscription paths

4. **Sidebar width classes**:

• `[.w-20_&]:hidden` — hide text when sidebar collapsed
• `[.w-64_&]:mr-4` — add margin for icon when sidebar expanded
• `[.w-20_&]:mx-auto` — center icon when sidebar collapsed

5. **Swap imports in `src/App.tsx`** layout props:

• Remove `SubscriptionDesktopMenu` / `SubscriptionMobileMenu` from `@fireact.dev/app` import
• Import custom versions
• Pass to `SubscriptionLayout` `desktopMenu` and `mobileMenu` props

See `references/navigation-customization.md` for full reference.

F. Customize Branding & Theme

Use when the user wants to change colors, fonts, or logo.

**Steps:**

1. **Modify `tailwind.config.js`** for custom colors/fonts:

   theme: {
     extend: {
       colors: {
         primary: { /* custom palette */ }
       }
     }
   }

2. **Modify `src/index.css`** for global styles

3. **Create custom Logo component** at