👨‍💻 Developer Guide

Getting Started

This guide is for developers who want to contribute to the TikTok Downloader project or integrate with our API.

Project Structure

Text

tiktok-downloader/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── page.tsx           # Home page
│   │   ├── download/page.tsx   # Download page
│   │   ├── history/page.tsx   # History page
│   │   ├── settings/page.tsx   # Settings page
│   │   ├── docs/page.tsx      # Documentation page
│   │   └── docs/[slug]/page.tsx # Dynamic docs pages
│   ├── components/            # React components
│   │   ├── common/            # Shared components
│   │   ├── layout/            # Layout components
│   │   ├── pages/             # Page-specific components
│   │   ├── preview/           # Media preview components
│   │   └── ui/                # UI component library
│   ├── lib/                   # Utility libraries
│   │   ├── api.ts             # TikTok API wrapper
│   │   ├── storage.ts         # Local storage management
│   │   ├── utils.ts           # General utilities
│   │   └── ...                # Other utilities
│   ├── types/                 # TypeScript definitions
│   └── styles/                # CSS and styling
├── public/
│   ├── docs/                  # Documentation markdown files
│   └── ...                    # Static assets
├── workers-api/               # Cloudflare Workers API
└── build/                     # Android build files

Tech Stack

Framework: Next.js 15 with App Router
Language: TypeScript
Styling: Tailwind CSS
Animations: Framer Motion
UI Components: Radix UI + Custom components
Icons: Lucide React
State Management: React hooks + Context
API: Cloudflare Workers
Mobile: Capacitor (Android)

Development Setup

Prerequisites

Node.js 18+
npm or pnpm
Git

Installation

Clone the repository

Bash

git clone https://github.com/zamdevio/clipx.git
cd clipx

Install dependencies
Bash
```
npm install
# or
pnpm install
```
Run development server
Bash
```
npm run dev
# or
pnpm dev
```
Open in browser Navigate to http://localhost:3000

Environment Variables

Create a .env.local file:

ENV

# API Configuration
NEXT_PUBLIC_API_URL=https://clipx.zamdev.workers.dev
NEXT_PUBLIC_APP_NAME="TikTok Downloader"

# Development
NODE_ENV=development

Architecture Overview

Frontend Architecture

The application uses Next.js 15 with the App Router pattern:

Pages: Located in src/app/ directory
Components: Reusable UI components in src/components/
Utilities: Helper functions in src/lib/
Types: TypeScript definitions in src/types/

State Management

The app uses React Context for global state:

SettingsContext: User preferences and settings
VolumeContext: Audio volume management
Theme: System theme detection and management

API Integration

The frontend communicates with a Cloudflare Workers API:

TikTokAPI: Main API wrapper class
Error Handling: Comprehensive error management
Retry Logic: Automatic retry for failed requests
Type Safety: Full TypeScript support

Component Development

Creating New Components

Create component file

TYPESCRIPT

// src/components/ui/my-component.tsx
import { cn } from '@/lib/utils';

interface MyComponentProps {
  className?: string;
  children: React.ReactNode;
}

export function MyComponent({ className, children }: MyComponentProps) {
  return (
    <div className={cn('base-styles', className)}>
      {children}
    </div>
  );
}

Add to index file

TYPESCRIPT

// src/components/ui/index.ts
export { MyComponent } from './my-component';

Use in pages

TYPESCRIPT

import { MyComponent } from '@/components/ui';

Component Guidelines

Use TypeScript: Always define proper interfaces
Follow naming: Use PascalCase for components
Include className: Allow style customization
Add accessibility: Include ARIA labels and roles
Use motion: Add animations with Framer Motion
Export from index: Export from component index files

UI Component Library

The project includes a custom UI component library:

Button: Enhanced button with animations
Input: Form input with validation
Modal: Accessible modal dialogs
Tooltip: Contextual help tooltips
Progress: Download progress indicators
Skeleton: Loading state components

API Development

TikTok API Wrapper

The TikTokAPI class handles all TikTok-related operations:

TYPESCRIPT

// src/lib/api.ts
export class TikTokAPI {
  static async getVideoInfo(url: string): Promise<TikTokResponse> {
    // Implementation
  }
  
  static async downloadVideo(url: string): Promise<Blob> {
    // Implementation
  }
  
  static getContentType(data: TikTokData): 'video' | 'image' {
    // Implementation
  }
}

Error Handling

Comprehensive error handling with user-friendly messages:

TYPESCRIPT

interface ErrorInfo {
  message: string;
  type: 'error' | 'warning' | 'info';
  code?: string;
  details?: string;
}

export function createErrorInfo(error: Error, context: string): ErrorInfo {
  // Implementation
}

API Best Practices

Type Safety: Use TypeScript interfaces
Error Handling: Always handle errors gracefully
Retry Logic: Implement exponential backoff
Validation: Validate inputs before processing
Documentation: Document all public methods

Testing

Testing Strategy

The project uses a comprehensive testing approach:

Unit Tests: Test individual functions and components
Integration Tests: Test component interactions
E2E Tests: Test complete user journeys
API Tests: Test API endpoints and responses

Running Tests

Bash

# Unit tests
npm run test

# Integration tests
npm run test:integration

# E2E tests
npm run test:e2e

# All tests
npm run test:all

Writing Tests

TYPESCRIPT

// Example component test
import { render, screen } from '@testing-library/react';
import { MyComponent } from '@/components/ui';

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(<MyComponent>Test content</MyComponent>);
    expect(screen.getByText('Test content')).toBeInTheDocument();
  });
});

Documentation System

Markdown Documentation

Documentation is stored as markdown files in public/docs/:

api.md: API documentation
user-guide.md: User guide
troubleshooting.md: Troubleshooting guide
faq.md: Frequently asked questions
developer-guide.md: This guide

Dynamic Documentation Pages

The /docs route dynamically loads markdown files:

TYPESCRIPT

// src/app/docs/[slug]/page.tsx
export default async function DocPage({ params }: { params: { slug: string } }) {
  const content = await getMarkdownContent(params.slug);
  return <MarkdownRenderer content={content} />;
}

Adding New Documentation

Create markdown file

Bash

# Create new doc file
touch public/docs/new-feature.md

Add to navigation

TYPESCRIPT

// Update navigation constants
const DOCS_NAV_ITEMS = [
  { title: 'New Feature', url: '/docs/new-feature' },
  // ... other items
];

Access via URL Navigate to /docs/new-feature

Mobile Development

Capacitor Integration

The project includes Capacitor for mobile app development:

Android: Full Android app support
iOS: iOS support (planned)
Native Features: Access to device APIs

Building Mobile App

Bash

# Build web app
npm run build

# Sync with Capacitor
npx cap sync

# Build Android
npx cap build android

# Run on device
npx cap run android

Mobile-Specific Features

File Downloads: Native file download handling
Storage: Local storage for offline functionality
Notifications: Push notifications (planned)
Sharing: Native sharing capabilities

Performance Optimization

Code Splitting

The app uses dynamic imports for code splitting:

TYPESCRIPT

// Lazy load components
const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <Skeleton />,
});

Image Optimization

Lazy Loading: Images load only when needed
Blur Placeholders: Smooth loading experience
Responsive Images: Different sizes for different screens

Bundle Analysis

Bash

# Analyze bundle size
npm run analyze

# Check for unused code
npm run check-unused

Deployment

Web Deployment

The app can be deployed to various platforms:

Vercel: Recommended for Next.js apps
Netlify: Static site deployment
Cloudflare Pages: Edge deployment
Railway: Full-stack deployment

Environment Configuration

Bash

# Production build
npm run build

# Start production server
npm run start

# Export static files
npm run export

CI/CD Pipeline

YAML

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
      - run: npm install
      - run: npm run build
      - run: npm run deploy

Contributing

Getting Started

Fork the repository

Create feature branch

Bash

git checkout -b feature/amazing-feature

Make changes
Run tests
Bash
```
npm run test
```
Commit changes
Bash
```
git commit -m 'Add amazing feature'
```

Push to branch

Bash

git push origin feature/amazing-feature

Open Pull Request

Code Style

TypeScript: Use strict TypeScript
ESLint: Follow ESLint rules
Prettier: Use Prettier for formatting
Conventional Commits: Use conventional commit messages

Pull Request Guidelines

Clear description: Explain what and why
Tests: Include tests for new features
Documentation: Update docs if needed
Breaking changes: Clearly mark breaking changes

Troubleshooting Development Issues

Common Issues

Build Errors

Bash

# Clear cache
rm -rf .next
npm run build

Type Errors

Bash

# Check types
npx tsc --noEmit

Dependency Issues

Bash

# Clear node_modules
rm -rf node_modules package-lock.json
npm install

Hot Reload Issues

Bash

# Restart dev server
npm run dev

Debugging

Browser DevTools: Use React DevTools
Console Logging: Add strategic console.logs
Network Tab: Monitor API requests
Performance Tab: Check for performance issues

Resources

Documentation

Tools

Community

GitHub Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For development support:

GitHub Issues: Technical problems
Discussions: General questions
Email: [email protected]
Discord: Community support