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:
- Check our Troubleshooting Guide
- Search GitHub Issues
- Join our Discord Community
- Email support at support@luffa.dev
Next Steps
After installation, you're ready to:
Welcome to the Luffa community! 🌱