Frequently Asked Questions

Common questions about using the Boilerplate App template to create new FlowState applications.

General

What is the Boilerplate App?

The Boilerplate App is a template package that provides a complete, working application structure for creating new FlowState micro-applications. It includes pre-configured routing, layout components, plugin architecture, and development tooling so you can start building features immediately rather than setting up infrastructure.

Who should use this template?

This template is designed for:

• FlowState developers creating new micro-applications
• Contributors adding new apps to the FlowState ecosystem
• Teams building internal tools using the FlowState platform

Why use a template instead of starting from scratch?

Using the boilerplate ensures:

• Consistency - All apps follow the same patterns and conventions
• Compatibility - Pre-configured integration with the host container
• Speed - Skip setup and start building features immediately
• Best practices - Includes proven patterns for routing, state, and lifecycle

Creating Apps

How do I create a new app from this template?

1. Copy the boilerplate directory:

   cp -r packages/apps/flowstate-app-boilerplate packages/apps/flowstate-app-myapp
   

2. Update package.json, flowstate.json, and src/plugin.ts with your app's identity

3. Run yarn install and yarn dev

See Creating a New App for detailed steps.

What should I name my app?

Follow these naming conventions:

Which port should I use for development?

Choose a unique port in the 3200-3299 range. Check packages/apps/*/vite.config.mts to see which ports are already in use. Common assignments:

Can I use a different icon for my app?

Yes. Icons come from Lucide React. Update both:

1. flowstate.json - use the icon name as a string (e.g., "layout-grid")
2. src/plugin.ts - import and use the React component (e.g., import { LayoutGrid } from 'lucide-react')

Development

What's the difference between standalone and embedded mode?

The standalone prop controls mode-specific behavior in components.

How do I add a new page to my app?

1. Create a page component in src/pages/:

   export function MyPage() {
     return <div>My Page Content</div>;
   }
   

2. Add a route in src/App.tsx:

   <Route path="mypage" element={<MyPage />} />
   

3. Add a navigation link in src/components/Sidebar.tsx:

   { path: '/mypage', label: 'My Page', icon: 'file', priority: 20 }
   

How do I access database collections?

Use RxDB hooks from @epicdm/flowstate-rxdb-react:

import { useRxCollection, useRxQuery } from '@epicdm/flowstate-rxdb-react';

function MyComponent() {
  const collection = useRxCollection('tasks');
  const { result: tasks } = useRxQuery(
    collection?.find({ selector: { status: 'pending' } })
  );

  return <TaskList tasks={tasks} />;
}

How do I add custom commands to my app?

Register commands in flowstate.json:

{
  "contributes": {
    "commands": [
      {
        "id": "myapp.createItem",
        "title": "Create New Item",
        "category": "My App"
      }
    ]
  }
}

Building & Deployment

How do I build my app for production?

yarn build

This generates:

• dist/index.js - CommonJS bundle
• dist/index.mjs - ESM bundle
• dist/index.d.ts - TypeScript declarations
• dist/index.css - Bundled styles

Why are some dependencies marked as external?

External dependencies (React, React Router, framework packages) are provided by the host container. Marking them external:

• Reduces bundle size
• Prevents duplicate instances
• Ensures consistent versions across apps

How do I add the app to the host container?

Register your plugin in the host container's plugin configuration:

import { myappPlugin } from '@epicdm/flowstate-app-myapp';

const plugins = [
  // ... other plugins
  myappPlugin,
];

The host container handles lazy loading, routing, and lifecycle management.

Technical

Which browsers are supported?

The boilerplate targets modern browsers:

• Chrome/Edge (last 2 versions)
• Firefox (last 2 versions)
• Safari (last 2 versions)

The Vite build configuration handles necessary transpilation.

What TypeScript version is required?

TypeScript 5.0 or higher. The template uses strict mode and modern features like:

• satisfies operator
• moduleResolution: "bundler"
• Strict null checks

Can I use different styling than Tailwind CSS?

Yes, but Tailwind is recommended for consistency with other FlowState apps. If you need custom styles:

1. Add your CSS framework to dependencies
2. Update postcss.config.js if needed
3. Import your styles in src/index.ts

The framework components use Tailwind, so some Tailwind configuration is still needed.

How do plugin lifecycle hooks work?

Plugins have two lifecycle hooks:

{
  onLoad: async (services) => {
    // Called when app is activated
    // Initialize resources, subscribe to services
    const db = services.get('database');
  },
  onUnload: async () => {
    // Called when app is deactivated
    // Clean up subscriptions, release resources
  },
}

Still Have Questions?

If your question isn't answered here:

• Check Getting Started for setup guidance
• Review Template Structure for technical details
• See Troubleshooting for common issues
• Ask in the development channel for additional help