Skip to main content

​
Installation

This guide covers everything you need to install and configure the framework, including prerequisites, multiple installation methods, and troubleshooting common issues.

​
Prerequisites

Before installing, ensure your system meets these requirements:

​
Node.js

Node.js 18.x or higher is required. We recommend using the latest LTS version for the best experience and security updates.
Check your Node.js version: 
node --version
If you need to install or upgrade Node.js: 
brew install node@20
We recommend using nvm (Node Version Manager) to manage multiple Node.js versions on your system.

​
Package Manager

Choose one of the following package managers:
  • npm (comes bundled with Node.js)
  • yarn 1.22+ or yarn 3+
  • pnpm 8+ (recommended for monorepos)
Install yarn or pnpm globally: 
npm install -g yarn

​
Code Editor

While any editor works, we recommend Visual Studio Code with these extensions:
  • ESLint - Linting and code quality
  • Prettier - Code formatting
  • TypeScript Vue Plugin / ES7+ React/Redux/React-Native snippets - Framework-specific tooling
  • Tailwind CSS IntelliSense - If using Tailwind

​
Installation Methods

The fastest way to get started is using our CLI scaffolding tool:
1

Run the Create Command

npx create-frontend-app@latest my-project
Replace my-project with your desired project name.
2

Choose Your Configuration

The CLI will prompt you for configuration options:
✔ Select a template › TypeScript
✔ Add routing? … Yes
✔ Add state management? … Yes
✔ Select a styling solution › Tailwind CSS
✔ Add testing utilities? … Yes
✔ Initialize git repository? … Yes
For most projects, we recommend choosing TypeScript, routing, and Tailwind CSS.
3

Navigate to Project

cd my-project
4

Install Dependencies

Dependencies are installed automatically, but if you need to reinstall:
npm install
5

Start Development Server

npm run dev
Your app will be running at http://localhost:3000

​
Method 2: Add to Existing Project

If you have an existing project and want to add the framework:
1

Install Core Package

npm install @frontend/core @frontend/router
2

Install Dev Dependencies

npm install -D @frontend/cli vite @vitejs/plugin-react typescript
3

Create Configuration

Create a vite.config.ts file in your project root:
vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { frontendPlugin } from '@frontend/vite-plugin'

export default defineConfig({
  plugins: [
    react(),
    frontendPlugin({
      router: true,
      stateManagement: true,
    }),
  ],
  resolve: {
    alias: {
      '@': '/src',
    },
  },
})
4

Update TypeScript Config

Update or create tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}
5

Add Scripts to package.json

package.json
{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
  }
}

​
Method 3: Manual Setup

If you prefer complete control over your setup, you can manually configure your project:
1

Initialize the project

mkdir my-project
cd my-project
npm init -y
2

Install core dependencies

npm install react react-dom
npm install -D vite @vitejs/plugin-react typescript @types/react @types/react-dom
3

Add configuration files

Create the necessary configuration files (vite.config.ts, tsconfig.json) as shown in Method 2.

​
Verify Installation

Run these commands to verify everything is working: 
# Check framework version
npx frontend --version

# Run development server
npm run dev

# Build for production
npm run build
If all commands execute without errors, you’re ready to start developing!

​
Configuration

​
Environment Variables

Create a .env.local file in your project root for environment-specific variables:
.env.local
# API Configuration
VITE_API_URL=https://api.example.com
VITE_API_KEY=your_api_key_here

# Feature Flags
VITE_ENABLE_ANALYTICS=true
VITE_ENABLE_DEBUG=false
Only variables prefixed with VITE_ are exposed to your client-side code. Never commit .env.local to version control.

​
Path Aliases

Path aliases are configured in tsconfig.json and vite.config.ts. Default alias is @ for the src directory: 
import { Button } from '@/components/Button'
import { useAuth } from '@/hooks/useAuth'

​
Troubleshooting

​
Port Already in Use

If port 3000 is already in use: 
# Specify a different port
npm run dev -- --port 3001
Or set it in vite.config.ts: 
export default defineConfig({
  server: {
    port: 3001,
  },
})

​
Module Not Found Errors

  1. Clear your package manager cache:
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
  1. Ensure all peer dependencies are installed
  2. Check for typos in import paths
  3. Verify path aliases are configured correctly

​
TypeScript Errors

If you’re seeing TypeScript errors:
  1. Make sure you have TypeScript installed: 
    npm install -D typescript @types/react @types/react-dom
  2. Restart your TypeScript server in VS Code:
    • Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
    • Type “TypeScript: Restart TS Server”
  3. Check your tsconfig.json is properly configured

​
Build Failures

Most build failures are due to type errors or missing dependencies. Check the error message carefully.
Common solutions:
  1. Run type checking separately: 
    npx tsc --noEmit
  2. Clear build cache: 
    rm -rf dist .vite
  3. Ensure all imports use correct file extensions in the build output

​
Performance Issues

If development server is slow:
  1. Enable SWC instead of Babel in vite.config.ts: 
    import react from '@vitejs/plugin-react-swc'
  2. Exclude large directories from file watching: 
    export default defineConfig({
  server: {
    watch: {
      ignored: ['**/node_modules/**', '**/dist/**'],
    },
  },
})
  3. Use pnpm for faster installs in monorepos

​
Next Steps

Now that you have everything installed:

Quick Start Guide

Build your first component in 5 minutes

Project Architecture

Understand the recommended project organization

Development Setup

Learn about advanced configuration options

Development Workflow

Explore development best practices

​
Additional Resources

For more information about the technologies used:
These resources provide comprehensive guides for the core technologies used in this project.

Build docs developers (and LLMs) love

Get started for freeTalk to us