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

2. State Reading Protocol

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

src/App.tsx

@fireact.dev/app

src/config/app.config.json

src/config/stripe.config.json

src/i18n/en.ts

src/components/

functions/src/index.ts

firestore.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

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

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

   src/components/Logo.tsx

   and import locally in

   App.tsx

4. SubscriptionLayout supports these props for nav theming:

   • navBackgroundColor

     — CSS class for nav background (e.g.,

     "bg-blue-900"

     )

   • navTextColor

     — CSS class for nav text (e.g.,

     "text-blue-100"

     )

G. Add Custom Cloud Functions

Use when the user wants to add backend logic.

Steps:

1. Create

   functions/src/<functionName>.ts

   :

   import { onCall } from 'firebase-functions/v2/https';
   
   export const myFunction = onCall(async (request) => {
     // Access global config
     const config = global.saasConfig;
     // Your logic here
     return { success: true };
   });
   

2. Access

   global.saasConfig

   for permissions, plans, Stripe keys

3. Export from

   functions/src/index.ts

   :

   export { myFunction } from './<functionName>';
   

4. Call from frontend:

   import { httpsCallable } from 'firebase/functions';
   
   const config = useConfig();
   const myFunction = httpsCallable(config.functions, 'myFunction');
   const result = await myFunction({ /* data */ });
   

5. Build:

   cd functions && npm run build

See

references/cloud-functions-patterns.md

H. Add Firestore Collections & Custom Data

Use when the user wants to store and retrieve custom data.

Steps:

1. Use Firestore SDK with

   config.db

   from

   useConfig()

   :

   import { collection, doc, getDocs, addDoc } from 'firebase/firestore';
   
   const config = useConfig();
   
   // Read
   const snapshot = await getDocs(collection(config.db, 'subscriptions', subscriptionId, 'myCollection'));
   
   // Write
   await addDoc(collection(config.db, 'subscriptions', subscriptionId, 'myCollection'), { ... });
   

2. Add security rules to

   firestore.rules

   following existing patterns:

   match /subscriptions/{docId}/myCollection/{docId2} {
     allow read: if request.auth != null
       && get(/databases/$(database)/documents/subscriptions/$(docId)).data.permissions.access.hasAny([request.auth.uid]);
     allow write: if request.auth != null
       && get(/databases/$(database)/documents/subscriptions/$(docId)).data.permissions.admin.hasAny([request.auth.uid]);
   }
   

3. Build components that read/write data using the patterns in

   references/component-patterns.md

4. Key Conventions (Always Follow)

• i18n: Use

  useTranslation()

  with

  t('key')

  for ALL user-facing strings. Never hardcode display text.
• Loading/error states: Always handle in subscription components — show spinner while loading, redirect on error.
• TailwindCSS only: No inline styles. Use Tailwind utility classes.
• Route config: Always add route key to

  src/config/app.config.json

  when adding a page.
• Subscription route protection: Always wrap subscription routes in

  <ProtectedSubscriptionRoute requiredPermissions={[...]}>

  .
• Subscription URL pattern: Paths follow

  /subscription/:id/<slug>

  .
• Verify after changes: Run

  npm run build

  and

  cd functions && npm run build

  to confirm no errors.

5. References

For detailed API documentation and code templates, see:

• Hooks & Contexts API — All hooks, their return types, and exported TypeScript types
• Routing Patterns — Three route groups, ProtectedSubscriptionRoute, config mapping
• Component Patterns — Templates for subscription, authenticated, and public pages
• Navigation Customization — Menu component patterns, SubscriptionLayout props
• Cloud Functions Patterns — Backend function templates, global config, frontend calling