Installation Guide

Get Luffa up and running in your project quickly with this step-by-step installation guide.

Quick Start

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

npx create-luffa-docs my-docs
cd my-docs
npm run dev

Your documentation site will be available at http://localhost:3000.

Manual Installation

Prerequisites

Before installing Luffa, make sure you have:

  • Node.js 18.17 or later
  • npm 9.0 or later (or yarn 1.22+, pnpm 8.0+)
  • Git for version control

Step 1: Create a New Project

# Create a new directory
mkdir my-luffa-docs
cd my-luffa-docs

# Initialize package.json
npm init -y

Step 2: Install Dependencies

# Install Luffa and required dependencies
npm install next@latest react@latest react-dom@latest

# Install Luffa-specific packages
npm install @mdx-js/loader @mdx-js/react @next/mdx
npm install @tailwindcss/typography @headlessui/react
npm install framer-motion clsx

# Install development dependencies
npm install -D typescript @types/react @types/node
npm install -D tailwindcss postcss autoprefixer
npm install -D eslint eslint-config-next

Step 3: Configure Next.js

Create next.config.mjs:

import createMDX from '@next/mdx'

/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions: ['ts', 'tsx', 'mdx'],
  experimental: {
    mdxRs: true,
  },
}

const withMDX = createMDX({
  // Add markdown plugins here
})

export default withMDX(nextConfig)

Step 4: Set Up TypeScript

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Step 5: Configure Tailwind CSS

Initialize Tailwind:

npx tailwindcss init -p

Update tailwind.config.ts:

import type { Config } from 'tailwindcss'

const config: Config = {
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  darkMode: 'selector',
  theme: {
    extend: {
      colors: {
        luffa: {
          50: '#f8fdf4',
          100: '#f0fae6',
          200: '#def4cc',
          300: '#c4e9a3',
          400: '#a3d974',
          500: '#7fc34f',
          600: '#60a839',
          700: '#4a8230',
          800: '#3d6829',
          900: '#345726',
          950: '#1e2f12',
        },
      },
    },
  },
  plugins: [require('@tailwindcss/typography')],
}

export default config

Step 6: Create Basic Structure

Create the basic directory structure:

src/
├── app/
│   ├── layout.tsx
│   ├── page.mdx
│   └── globals.css
└── components/
    ├── Layout.tsx
    └── Navigation.tsx

Create src/app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

Step 7: Add Package Scripts

Update your package.json:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

Advanced Installation Options

With AI Search

To enable AI-powered search functionality:

# Install AI search dependencies
npm install openai @upstash/vector react-markdown
npm install @heroicons/react gray-matter

Set up environment variables in .env.local:

# OpenAI API key for embeddings and chat
OPENAI_API_KEY=sk-your-openai-api-key

# Upstash Vector database for RAG search
UPSTASH_VECTOR_REST_URL=your-upstash-vector-url
UPSTASH_VECTOR_REST_TOKEN=your-upstash-vector-token

With Analytics

For documentation analytics:

# Install analytics packages
npm install @vercel/analytics @vercel/speed-insights
# or
npm install google-analytics gtag

With CMS Integration

For content management system integration:

# Popular CMS integrations
npm install contentful       # Contentful
npm install @sanity/client   # Sanity
npm install @strapi/sdk      # Strapi

Deployment

Vercel (Recommended)

# Install Vercel CLI
npm install -g vercel

# Deploy to Vercel
vercel

# Set environment variables in Vercel dashboard

Netlify

# Install Netlify CLI
npm install -g netlify-cli

# Build and deploy
npm run build
netlify deploy --prod --dir=.next

Self-Hosted

# Build for production
npm run build

# Start production server
npm start

# Or use PM2 for production
npm install -g pm2
pm2 start npm --name "luffa-docs" -- start

Docker Installation

Create Dockerfile:

FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

RUN npm run build

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000

CMD ["node", "server.js"]

Build and run:

# Build Docker image
docker build -t luffa-docs .

# Run container
docker run -p 3000:3000 luffa-docs

Environment Variables

Create .env.example for your team:

# Required for AI search
OPENAI_API_KEY=sk-your-openai-key
UPSTASH_VECTOR_REST_URL=https://your-vector-db.upstash.io
UPSTASH_VECTOR_REST_TOKEN=your-token

# Optional analytics
VERCEL_ANALYTICS_ID=your-analytics-id
GOOGLE_ANALYTICS_ID=GA-your-id

# Optional CMS
CONTENTFUL_SPACE_ID=your-space-id
CONTENTFUL_ACCESS_TOKEN=your-token

Troubleshooting

Common Issues

Node.js Version Mismatch

# Check your Node.js version
node --version

# Use nvm to switch versions
nvm install 18
nvm use 18

MDX Compilation Errors

# Clear Next.js cache
rm -rf .next
npm run dev

Build Failures

# Check for TypeScript errors
npm run build 2>&1 | grep "error TS"

# Clear all caches
rm -rf .next node_modules package-lock.json
npm install
npm run build

Memory Issues During Build

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npm run build

Getting Help

If you encounter issues during installation:

  1. Check our Troubleshooting Guide
  2. Search GitHub Issues
  3. Join our Discord Community
  4. Email support at support@luffa.dev

Next Steps

After installation, you're ready to:

  1. Create your first documentation
  2. Set up AI-powered search
  3. Customize the theme
  4. Deploy to production

Welcome to the Luffa community! 🌱

Was this page helpful?