---
sidebar_position: 2
---

# Local Development

This guide covers how to set up and run the TFT Minting Transition Plan site locally for development and testing.

## Prerequisites

### Required Software

- **Node.js**: Version 18.0 or higher
- **npm**: Comes with Node.js
- **Git**: For version control

### Check Your Versions

```bash
node --version  # Should be v18.0.0 or higher
npm --version   # Should be 8.0.0 or higher
git --version   # Any recent version
```

### Installing Node.js

If you don't have Node.js 18+:

**Linux (Ubuntu/Debian)**:
```bash
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
```

**macOS**:
```bash
brew install node@18
```

**Using nvm (recommended)**:
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
```

---

## Initial Setup

### 1. Clone the Repository

```bash
git clone https://github.com/mik-tf/minting_plan.git
cd minting_plan
```

### 2. Install Dependencies

```bash
npm install
```

This will install all required packages listed in `package.json`, including:
- Docusaurus core
- React
- MDX support
- Theme packages

:::info First Install
The first `npm install` will take 1-2 minutes as it downloads all dependencies. Subsequent installs will be faster thanks to npm cache.
:::

---

## Development Server

### Start the Dev Server

```bash
npm start
```

This command:
- Starts a local development server
- Opens your browser to `http://localhost:3000`
- Enables hot reloading (changes appear immediately)
- Shows build errors in the terminal and browser

### What You'll See

```
[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/
```

:::tip Hot Reloading
Edit any markdown file and save - your browser will automatically refresh with changes. No need to restart the server!
:::

### Stop the Server

Press `Ctrl+C` in the terminal where the server is running.

---

## Building for Production

### Create Production Build

```bash
npm run build
```

This command:
- Creates optimized production files in `build/` directory
- Minifies JavaScript and CSS
- Generates static HTML for all pages
- Checks for broken links

### Preview Production Build

```bash
npm run serve
```

This serves the production build locally at `http://localhost:3000` so you can test it before deployment.

:::warning Test Before Push
Always run `npm run build` before pushing to ensure there are no build errors. The production build is stricter than dev mode.
:::

---

## Common Development Tasks

### Adding a New Page

1. Create a new `.md` file in the appropriate docs folder:
   ```bash
   touch docs/core-concepts/new-concept.md
   ```

2. Add frontmatter:
   ```markdown
   ---
   sidebar_position: 5
   ---
   
   # New Concept Title
   
   Your content here...
   ```

3. The page appears automatically in the sidebar!

### Editing Existing Content

1. Navigate to the file (e.g., `docs/intro.md`)
2. Make your changes
3. Save the file
4. Browser auto-refreshes with changes

### Adding Images

1. Place images in `static/img/`:
   ```bash
   cp ~/my-image.png static/img/
   ```

2. Reference in markdown:
   ```markdown
   ![Alt text](./img/my-image.png)
   ```

---

## Project Structure

```
minting_plan/
├── docs/                          # All documentation content
│   ├── intro.md                   # Homepage
│   ├── core-concepts/             # Core concept docs
│   ├── appendix/                  # Meeting notes, etc.
│   └── ops/                       # Operations guides
├── static/                        # Static assets
│   ├── img/                       # Images
│   └── CNAME                      # Custom domain file
├── src/                           # Custom React components
│   ├── css/                       # Custom styles
│   └── pages/                     # Custom pages (optional)
├── docusaurus.config.js           # Site configuration
├── sidebars.js                    # Sidebar structure
├── package.json                   # Dependencies
└── .github/workflows/             # GitHub Actions
    └── deploy.yml                 # Auto-deployment
```

---

## Useful Commands

### Clear Cache

If you see weird behavior, clear the cache:

```bash
npm run clear
```

### Check for Build Issues

```bash
npm run build
```

Look for:
- ✅ Success: Build completed
- ❌ Errors: Broken links, invalid markdown, missing files

### Format Code (if using Prettier)

```bash
npx prettier --write "docs/**/*.md"
```

---

## Development Workflow

### Typical Workflow

1. **Pull latest changes**
   ```bash
   git pull origin main
   ```

2. **Start dev server**
   ```bash
   npm start
   ```

3. **Make changes**
   - Edit markdown files in `docs/`
   - See changes instantly in browser

4. **Test production build**
   ```bash
   npm run build
   ```

5. **Commit and push**
   ```bash
   git add .
   git commit -m "Description of changes"
   git push origin main
   ```

6. **Auto-deployment**
   - GitHub Actions builds and deploys automatically
   - Check Actions tab for status
   - Site updates at plan.threefold.pro in ~3 minutes

---

## Troubleshooting

### Port 3000 Already in Use

**Error**: `Something is already running on port 3000`

**Solution**:
```bash
# Find and kill the process
lsof -i :3000
kill -9 <PID>

# Or use a different port
npm start -- --port 3001
```

### Module Not Found Errors

**Error**: `Cannot find module '@docusaurus/...'`

**Solution**:
```bash
# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
```

### Build Fails Locally

**Error**: Build fails with various errors

**Solution**:
```bash
# Clear cache and rebuild
npm run clear
npm run build
```

### Changes Not Appearing

**Problem**: Saved changes don't show in browser

**Solution**:
1. Check the terminal for build errors
2. Hard refresh browser: `Ctrl+Shift+R` (Linux/Win) or `Cmd+Shift+R` (Mac)
3. Restart dev server: `Ctrl+C`, then `npm start`

### Node Version Issues

**Error**: `The engine "node" is incompatible with this module`

**Solution**:
```bash
# Check your version
node --version

# Install correct version using nvm
nvm install 18
nvm use 18
```

---

## Best Practices

### Before Committing

✅ **Do**:
- Test build locally: `npm run build`
- Check for broken links in build output
- Preview with `npm run serve`
- Write clear commit messages

❌ **Don't**:
- Commit `node_modules/` (it's in .gitignore)
- Commit `build/` directory (it's generated)
- Push without testing build
- Use absolute URLs for internal links

### Writing Documentation

✅ **Good practices**:
- Use relative links: `[link](./other-page.md)`
- Add alt text to images: `![Description](./img/pic.png)`
- Use frontmatter for sidebar position
- Keep markdown files in appropriate folders

❌ **Avoid**:
- Absolute URLs for internal pages
- Missing alt text on images
- Inconsistent heading levels
- Very long lines (wrap at ~100 chars)

---

## IDE Setup

### VS Code (Recommended)

Install these extensions for better experience:

- **Markdown All in One**: Markdown preview and shortcuts
- **Prettier**: Code formatting
- **ESLint**: JavaScript linting

### Settings

Add to `.vscode/settings.json`:

```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[markdown]": {
    "editor.wordWrap": "on"
  }
}
```

---

## Next Steps

- [Deployment](./deployment.md) - Deploy to plan.threefold.pro
- [Content Updates](./content-updates.md) - Learn content management workflows