Installation

Install Open Tarteel and set up your development environment

Prerequisites

Before installing Open Tarteel, ensure you have the following installed on your system:

Node.js

Version 20 or higher required

Package Manager

npm, yarn, pnpm, or bun

Open Tarteel uses Next.js 15 and React 19, which require Node.js 20 or higher.

Installation Steps

1. Clone the Repository

   Clone the Open Tarteel repository from GitHub:

   HTTPS

   git clone https://github.com/adelpro/open-tarteel.git
   cd open-tarteel
   
2. Install Dependencies

   Install all required dependencies using your preferred package manager:

   npm

   npm install
   

   The installation includes all necessary dependencies:

   • Next.js 15 with React 19
   • Jotai for state management
   • Tailwind CSS for styling
   • Serwist for PWA capabilities
   • TypeScript and ESLint for development
3. Verify Installation

   Verify that all dependencies are installed correctly:

   npm

   npm run type-check
   

   If no TypeScript errors appear, your installation is successful!

Development Scripts

Open Tarteel comes with several useful npm scripts defined in package.json:

Core Scripts

Development Server

npm run dev
# Starts Next.js development server at http://localhost:3000

Code Quality Scripts

Linting

npm run lint
# Runs ESLint to check for code issues

Advanced Scripts

React Scan

npm run dev:scan
# Scans application with React Scan at localhost:3000

Project Structure

After installation, your project structure will look like this:

open-tarteel/
├── src/
│   ├── app/              # Next.js App Router pages
│   │   ├── layout.tsx    # Root layout with Jotai provider
│   │   ├── page.tsx      # Home page with reciter selector
│   │   └── reciter/      # Dynamic reciter pages
│   ├── components/       # React components
│   │   ├── player.tsx    # Audio player component
│   │   ├── reciter-selector.tsx
│   │   └── ...
│   ├── jotai/           # Jotai atoms for state management
│   │   └── atom.ts      # Global state atoms
│   ├── hooks/           # Custom React hooks
│   ├── utils/           # Utility functions
│   └── types/           # TypeScript type definitions
├── public/              # Static assets
├── package.json         # Dependencies and scripts
├── next.config.ts       # Next.js configuration
├── tailwind.config.ts   # Tailwind CSS configuration
└── tsconfig.json        # TypeScript configuration

Key Dependencies

Runtime Dependencies

package.json

{
  "dependencies": {
    "next": "^15.4.2",
    "react": "^19.1.0",
    "react-dom": "^19.1.0",
    "jotai": "^2.11.1",
    "@serwist/next": "^9.0.12",
    "wavesurfer.js": "^7.10.1",
    "fuse.js": "^7.1.0",
    "react-icons": "^5.5.0",
    "tailwind-merge": "^3.3.1"
  }
}

Development Dependencies

package.json

{
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20",
    "@types/react": "^19.0.10",
    "eslint": "^9.18.0",
    "prettier": "^3.4.2",
    "tailwindcss": "^3.4.1",
    "husky": "^9.1.7",
    "lint-staged": "^15.4.1"
  }
}

Configuration Files

Next.js Configuration

The next.config.ts file includes PWA support with Serwist:

next.config.ts

import withSerwistInit from '@serwist/next';

const withSerwist = withSerwistInit({
  swSrc: 'src/sw.ts',
  swDest: 'public/sw.js',
  cacheOnNavigation: true,
  disable: !isProduction,
  maximumFileSizeToCacheInBytes: 100 * 1024 * 1024, // 100MB
});

const nextConfig = {
  reactStrictMode: !isProduction,
  transpilePackages: ['jotai-devtools'],
  productionBrowserSourceMaps: isProduction,
  compiler: {
    removeConsole: isProduction && { exclude: ['error'] },
  },
};

export default withSerwist(nextConfig);

Tailwind CSS Configuration

Tailwind is configured with custom animations and plugins:

tailwind.config.ts

module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'],
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    require('tailwindcss-animated'),
  ],
};

Git Hooks

Open Tarteel uses Husky and lint-staged for pre-commit hooks:

package.json

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "prettier --write",
      "eslint --fix"
    ],
    "*.{json,md,css}": "prettier --write"
  }
}

Git hooks automatically format and lint your code before commits, ensuring code quality consistency.

Environment Setup

Open Tarteel doesn’t require environment variables for basic usage. However, if you need to customize behavior:

.env.local (optional)

# Development mode
NODE_ENV=development

# Bundle analyzer
ANALYZE=false

Troubleshooting

Node version error

Ensure you’re using Node.js 20 or higher:

node --version

If needed, use nvm to install the correct version:

nvm install 20
nvm use 20

Installation fails with peer dependency warnings

These warnings are usually safe to ignore with Next.js 15 and React 19. If you encounter issues, try:

npm install --legacy-peer-deps

Port 3000 already in use

Change the port by modifying the dev script:

next dev -p 3001

Or set the PORT environment variable:

PORT=3001 npm run dev

TypeScript errors after installation

Clean and reinstall dependencies:

rm -rf node_modules .next
npm install
npm run type-check

Next Steps

Now that you have Open Tarteel installed, proceed to the Quick Start guide to run the application:

Quick Start Guide

Learn how to start the development server and use Open Tarteel