docs_tfgrid_economics/docsarchive/ops/local-development.md

sidebar_position

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

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

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

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

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.

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

   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

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:

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

---

Next Steps

• Deployment - Deploy to plan.threefold.pro
• Content Updates - Learn content management workflows