@1fe/starter-app

1fe Starter App 🚀

A production-ready template for creating your own 1fe instance. This application serves as both the reference implementation powering demo.1fe.com and as the git template used by create-1fe-app.

🎯 What is this?

This starter app demonstrates how to build a complete 1fe instance using @1fe/server and @1fe/shell. It includes:

• Examples for live configurations for live configurations, CSP settings, and environment management
• Two environments: Integration and Production setups
• Example widgets and plugin integrations

📋 Prerequisites

• Node.js >= 22
• Yarn (package manager)

🚀 Quick Start

1. Using create-1fe-app (Recommended)

npx @1fe/create-1fe-app my-1fe-app
cd my-1fe-app
yarn install
yarn dev

2. Access Your Application by going to http://localhost:3001

📦 Project Structure

src/
├── configs/
│   ├── ecosystem-configs.ts    # Live configurations
│   ├── critical-libs.ts        # Critical library URLs
│   └── env.ts                  # Environment configuration
├── csp-configs.ts              # Content Security Policy settings
├── server.ts                   # Express server setup
├── shell/                      # Shell components and utilities
└── public/                     # Static assets

⚙️ Configuration

Environment Variables

Create a .env file based on .env.example:

Variable	Description	Default
PORT	Server port	3001
NODE_ENV	Environment mode	development
SERVER_BUILD_NUMBER	Build identifier	local

Live Configurations

Update src/configs/ecosystem-configs.ts to point to your CDN:

export const configManagement: OneFEConfigManagement = {
  widgetVersions: {
    url: 'https://your-cdn.com/configs/widget-versions.json',
  },
  libraryVersions: {
    url: 'https://your-cdn.com/configs/lib-versions.json',
  },
  dynamicConfigs: {
    url: 'https://your-cdn.com/configs/live.json',
  },
  refreshMs: 30 * 1000,
};

CSP Configuration

Modify src/csp-configs.ts to allow your CDN domains:

export const cspConfigs = {
  'script-src': [
    "'self'",
    "'unsafe-inline'",
    'https://your-cdn.com',
    // ... other sources
  ],
  // ... other CSP directives
};

🛠️ Development Commands

# Start development server (client + server)
yarn dev

# Build for production
yarn build

# Start production server
yarn start

# Run tests
yarn test

# Type checking
yarn typecheck

# Linting
yarn lint

🌍 Deployment

This starter app can be deployed to any platform that supports Node.js applications:

Deploy to Render

Deploy to Heroku

Deploy to Vercel

yarn global add vercel
vercel --prod

Deploy to Railway

yarn global add @railway/cli
railway deploy

Deploy to AWS/Azure/GCP

Follow the respective platform documentation for Node.js applications. The built application is a standard Express.js server.

🔗 Widget Integration

Adding New Widgets

• Build your widget using 1fe-widget-starter-kit
• Deploy widget assets to your CDN
• Update widget-versions.json with your widget's information
• Configure the widget in your live.json file
• Update CSP settings if needed for new domains

Example Widget Configuration

// In your live.json
{
  "widgets": {
    "basePrefix": "https://your-cdn.com/widgets/",
    "configs": [
      {
        "widgetId": "@your-org/your-widget",
        "plugin": {
          "enabled": true,
          "route": "/your-widget"
        }
      }
    ]
  }
}

🔧 Customization

Branding & Styling

• Update src/shell/components/ for custom layout components
• Modify CSS variables in your shell styles
• Replace favicon and other assets in src/public/

Adding Custom Utilities

• Extend the shell utilities in src/shell/utils/
• Update the platform props interface
• Ensure new utilities are available to widgets via the sandbox

Environment-Specific Configuration

• Create environment-specific config files
• Use environment variables for sensitive data
• Set up different CDN endpoints per environment

🤝 Related Projects

• 1fe - Core 1fe packages and CLI tools
• 1fe-widget-starter-kit - Template for building widgets
• 1fe-playground - Development sandbox
• 1fe-ci-cd - CI/CD pipeline templates

📖 Documentation

• 1fe Documentation - Complete platform documentation
• Getting Started Guide - Step-by-step setup
• Architecture Overview - How 1fe works
• Deployment Guide - Production deployment

🐛 Troubleshooting

Common Issues

CSP Errors: Make sure your CDN domains are added to csp-configs.ts Widget Loading Failures: Verify your live configurations are accessible and valid Build Errors: Ensure all dependencies are installed and Node.js version is >= 22

Getting Help

• Check the documentation
• Search existing issues
• Ask questions in GitHub Discussions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Ready to build your 1fe instance? Check out our comprehensive documentation or explore the live demo!