Building and Running the Project

Learn how to build, test, and run Open Tarteel in different modes

Development Mode

Open Tarteel provides multiple development server options for different use cases.

Standard Development Server

Start the Next.js development server with hot reload:

npm

npm run dev

The application will be available at http://localhost:3000.

Turbopack Development Server

Use Next.js with Turbopack for faster builds and hot module replacement:

npm

npm run dev:turbo

Turbopack is Next.js’s next-generation bundler, providing significantly faster refresh times during development.

Development with React Scan

Analyze React component renders and performance:

npm run dev:scan

This launches React Scan at http://localhost:3000 to help identify performance bottlenecks.

Debug Mode with Inspector

Start the development server with Node.js inspector for debugging:

npm run dev:inspect

You can then attach a debugger (Chrome DevTools or VS Code) to debug server-side code.

Code Quality Checks

Linting

Run ESLint to check for code quality issues:

Check for issues

npm run lint

Linting is automatically run on staged files before each commit via Husky hooks.

Type Checking

Verify TypeScript types without emitting files:

npm run type-check

This runs the TypeScript compiler in no-emit mode to catch type errors.

Code Formatting

Format all files using Prettier:

npm run format

Prettier automatically formats:

• JavaScript/TypeScript files (.js, .jsx, .ts, .tsx)
• JSON files
• Markdown files
• CSS files

Building for Production

1. Run Production Build

   Create an optimized production build:

   npm

   npm run build
   

   This command:

   • Compiles TypeScript
   • Bundles all assets
   • Optimizes code for production
   • Generates static pages where possible
   • Creates service worker for PWA
2. Start Production Server

   After building, start the production server:

   npm

   npm start
   

   The production server will run at http://localhost:3000.

Always test your changes with a production build before submitting a pull request. Development and production builds can behave differently.

Available Scripts

Here’s a complete reference of all npm scripts in the project:

Script	Description
dev	Start development server
dev:turbo	Start development server with Turbopack
dev:scan	Start development server with React Scan
dev:inspect	Start development server with Node.js inspector
build	Create production build
start	Start production server
lint	Run ESLint checks
lint:fix	Run ESLint and auto-fix issues
type-check	Run TypeScript type checking
format	Format code with Prettier
prepare	Install Husky git hooks

Git Hooks

The project uses Husky for Git hooks to ensure code quality:

Pre-commit Hook

Automatically runs before each commit:

# Runs lint-staged on staged files
- Prettier formatting on *.{js,jsx,ts,tsx,json,md,css}
- ESLint with auto-fix on *.{js,jsx,ts,tsx}

Commit Message Hook

Enforces conventional commit format using Commitlint:

type(scope): subject

Examples:
feat(player): add shuffle functionality
fix(ui): resolve mobile layout issue
docs(readme): update installation steps

Valid commit types: feat, fix, docs, style, refactor, perf, test, chore, ci, build

Build Output

After running npm run build, you’ll find:

• .next/ - Next.js build output and cache
• public/sw.js - Generated service worker for PWA
• .next/static/ - Static assets and JavaScript bundles

Performance Optimization

The production build automatically includes:

• Code splitting - Automatic route-based splitting
• Tree shaking - Removes unused code
• Minification - JavaScript and CSS compression
• Image optimization - Automatic image optimization via Next.js
• Bundle analysis - Available via @next/bundle-analyzer

Troubleshooting

Build Failures

If the build fails:

1. Clear Next.js cache:

   rm -rf .next
   npm run build
   

2. Check for TypeScript errors:

   npm run type-check
   

3. Check for ESLint errors:

   npm run lint
   

Slow Build Times

• Use dev:turbo for faster development builds
• Clear .next cache periodically
• Check for circular dependencies

For more information on Next.js build optimization, see the Next.js documentation.