Environment Setup

This guide will help you set up your local development environment for the Lonely Planet frontend.

Prerequisites

• Node.js (see .nvmrc for version)
• npm (comes with Node.js)
• Git
• A code editor (we recommend VS Code with our recommended extensions)

Step-by-Step Setup

1. Clone the Repository

git clone git@github.com:lonelyplanet/lp-frontend-astro.git
cd lp-frontend-astro

2. Node.js Setup

We use a specific Node.js version (defined in .nvmrc). You can manage Node.js versions using one of these tools:

# Using nvm
nvm use

# Using asdf
asdf local nodejs $(cat .nvmrc)

# Using n
n auto

Note for asdf users: Set this environment variable to recognize .nvmrc:

export ASDF_NODEJS_LEGACY_FILE_DYNAMIC_STRATEGY=latest_available

3. Environment Variables

# Copy the example env file
cp .env.example .env.local

The .env.local file is git-ignored and should never be committed. It contains your local development secrets.

• See .env.example for required variables

4. Install Dependencies

# Fresh install (recommended for clean installs)
npm run fresh

# Regular install
npm install

5. Start Development Server

# Regular development
npm run dev

# Development with structured logging
npm run dev:logger

Visit http://local.lonelyplanet.com:3000 to see the site.

VS Code or Cursor Setup

Our repository includes VS Code or Cursor configuration that will automatically:

• Suggest required extensions on first open
• Apply consistent editor settings
• Enable TypeScript features
• Configure debugging

Required extensions will be automatically suggested when you open the project. You can also install them manually:

1. Core Extensions (auto-suggested)

   • Astro
   • Tailwind CSS IntelliSense
   • ESLint
   • Prettier

2. Recommended Extensions (optional but helpful)

   • GraphQL
   • Git Lens

VS Code settings are checked into:

• .vscode/settings.json - Editor settings
• .vscode/extensions.json - Extension recommendations
• .vscode/launch.json - Debugger configuration

Common Issues

Server Island Rendering

If you see errors about mismatched server island rendering:

1. Ensure ASTRO_KEY is set in .env.local
2. Restart the development server

GraphQL Type Generation

If you see TypeScript errors about missing GraphQL types:

1. Ensure the GraphQL schema is up to date
2. Run npm run codegen or npm run codegen:watch

Port Conflicts

If port 3000 is in use:

1. Kill the existing process
2. Use port 3001 instead

Verifying Your Setup

Run these checks to ensure everything is working:

1. Development Server

   npm run dev

   Should start without errors and show the homepage

2. Type Checking (coming soon)

   npm run typecheck

   Should pass without errors

3. Linting

   npm run lint

   Should pass without errors

4. GraphQL Types (coming soon)

   npm run codegen

   Should generate types without errors

Next Steps

Once your environment is set up:

1. Read our Core Concepts guide
2. Make your First Contribution
3. Review our Component Patterns

Getting Help

If you encounter issues:

1. Check the Common Issues section above
2. Search our documentation
3. Ask in #lp-frontend Slack channel