Skip to main content

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

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

​
Code Quality Scripts

npm run lint
# Runs ESLint to check for code issues

​
Advanced Scripts

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

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
These warnings are usually safe to ignore with Next.js 15 and React 19. If you encounter issues, try:
npm install --legacy-peer-deps
Change the port by modifying the dev script:
next dev -p 3001
Or set the PORT environment variable:
PORT=3001 npm run dev
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

Build docs developers (and LLMs) love

Get started for freeTalk to us