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

winget install OpenJS.NodeJS.LTS

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

nvm install --lts
nvm use --lts

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

npm install -g pnpm

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

Method 1: Create a New Project (Recommended)

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

Run the Create Command

npx create-frontend-app@latest my-project

yarn create frontend-app my-project

pnpm create frontend-app my-project

Replace my-project with your desired project name.

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.

Navigate to Project

cd my-project

Install Dependencies

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

npm install

yarn install

pnpm install

Start Development Server

npm run dev

yarn dev

pnpm 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:

Install Core Package

npm install @frontend/core @frontend/router

yarn add @frontend/core @frontend/router

pnpm add @frontend/core @frontend/router

Install Dev Dependencies

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

yarn add -D @frontend/cli vite @vitejs/plugin-react typescript

pnpm add -D @frontend/cli vite @vitejs/plugin-react typescript

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',
    },
  },
})

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" }]
}

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:

Initialize the project

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

Install core dependencies

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

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

Clear your package manager cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

yarn cache clean
rm -rf node_modules yarn.lock
yarn install

pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install

Ensure all peer dependencies are installed
Check for typos in import paths
Verify path aliases are configured correctly

TypeScript Errors

If you’re seeing TypeScript errors:

Make sure you have TypeScript installed:

npm install -D typescript @types/react @types/react-dom

Restart your TypeScript server in VS Code:
- Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
- Type “TypeScript: Restart TS Server”
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:

Run type checking separately:
npx tsc --noEmit
Clear build cache:
rm -rf dist .vite
Ensure all imports use correct file extensions in the build output

Performance Issues

If development server is slow:

Enable SWC instead of Babel in vite.config.ts:

import react from '@vitejs/plugin-react-swc'

Exclude large directories from file watching:

export default defineConfig({
  server: {
    watch: {
      ignored: ['**/node_modules/**', '**/dist/**'],
    },
  },
})

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.

Getting Started

Core Concepts

Development

Guides

Installation

Installation

Prerequisites

Node.js

Package Manager

Code Editor

Installation Methods

Method 1: Create a New Project (Recommended)

Method 2: Add to Existing Project

Method 3: Manual Setup

Verify Installation

Configuration

Environment Variables

Path Aliases

Troubleshooting

Port Already in Use

Module Not Found Errors

TypeScript Errors

Build Failures

Performance Issues

Next Steps

Quick Start Guide

Project Architecture

Development Setup

Development Workflow

Additional Resources

​Installation

​Prerequisites

​Node.js

​Package Manager

​Code Editor

​Installation Methods

​Method 1: Create a New Project (Recommended)

​Method 2: Add to Existing Project

​Method 3: Manual Setup

​Verify Installation

​Configuration

​Environment Variables

​Path Aliases

​Troubleshooting

​Port Already in Use

​Module Not Found Errors

​TypeScript Errors

​Build Failures

​Performance Issues

​Next Steps

Quick Start Guide

Project Architecture

Development Setup

Development Workflow

​Additional Resources

Installation

Prerequisites

Node.js

Package Manager

Code Editor

Installation Methods

Method 1: Create a New Project (Recommended)

Method 2: Add to Existing Project

Method 3: Manual Setup

Verify Installation

Configuration

Environment Variables

Path Aliases

Troubleshooting

Port Already in Use

Module Not Found Errors

TypeScript Errors

Build Failures

Performance Issues

Next Steps

Additional Resources