Skip to main content

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​

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

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

macOS:

brew install node@18

Using nvm (recommended):

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​

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

2. Install Dependencies​

npm install

This will install all required packages listed in package.json, including:

  • Docusaurus core
  • React
  • MDX support
  • Theme packages
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​

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

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​

npm run serve

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

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:

    touch docs/core-concepts/new-concept.md

  2. Add frontmatter:

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

    cp ~/my-image.png static/img/

  2. Reference in 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:

npm run clear

Check for Build Issues​

npm run build

Look for:

  • ✅ Success: Build completed
  • ❌ Errors: Broken links, invalid markdown, missing files

Format Code (if using Prettier)​

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

Development Workflow​

Typical Workflow​

  1. Pull latest changes

    git pull origin main

  2. Start dev server

    npm start

  3. Make changes

    • Edit markdown files in docs/
    • See changes instantly in browser

  4. Test production build

    npm run build

  5. Commit and push

    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:

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

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Build Fails Locally​

Error: Build fails with various errors

Solution:

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

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

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:

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

Next Steps​