Development Setup

This guide will help you set up a local development environment for contributing to Tourista.

Prerequisites

• Node.js 16.0 or higher

• pnpm 10.6.2 or higher (package manager)

• Git for version control

• A Next.js test project (your own or the demo app)

Library Repository Setup

1. Clone the Library Repository

git clone https://github.com/RicSala/tourista.git
cd tourista

2. Quick Development Setup

The easiest way to get started:

pnpm run dev:setup

This script (scripts/setup-dev.sh) will:

1. Install dependencies

2. Build the library once

3. Create a global pnpm link

4. Start watch mode for auto-rebuilding

3. Manual Setup (Alternative)

If you prefer manual setup:

# Install dependencies
pnpm install

# Build the library
pnpm run build

# Create global link
pnpm run link

# Start watch mode
pnpm run dev

Linking to Your Test Project

In Your Next.js Application

After setting up the library, link it in your test project:

# Navigate to your Next.js app
cd ../your-nextjs-app

# Link the library (note: it's "tourista" not "Tourista" for local link)
pnpm link tourista --global

Using the Demo Application

If you're using the tourista-demo repository:

# Clone the demo
cd ..
git clone [demo-repo-url] tourista-demo
cd tourista-demo

# Use the demo's link script
pnpm run dev:link

The demo's dev:link script handles cleanup and linking automatically.

Available Scripts in Library

Script	Description
pnpm run build	Build library with tsup (cjs, esm, dts)
pnpm run dev	Watch mode - rebuilds on changes
pnpm run dev:setup	Run setup script (install, build, link, watch)
pnpm run type:check	TypeScript type checking
pnpm run lint	Run ESLint
pnpm run lint:fix	Auto-fix ESLint issues
pnpm run link	Create global pnpm link
pnpm run unlink	Remove global pnpm link
pnpm run version:patch	Bump patch version
pnpm run version:minor	Bump minor version
pnpm run version:major	Bump major version

Build Configuration

The library uses tsup for building with the following configuration:

tsup src/index.ts --format cjs,esm --dts --clean --no-splitting

• Formats: CommonJS and ESM modules

• Type Definitions: Generated automatically

• Clean Build: Removes previous build artifacts

• No Code Splitting: Single bundle output

Type Checking

Always run type checking before committing:

pnpm run type:check

This ensures no TypeScript errors are introduced.

Linting

The project uses ESLint with TypeScript support:

# Check for issues
pnpm run lint

# Auto-fix issues
pnpm run lint:fix

Project Structure

tourista/                     # Library repository
├── src/                      # Source code
│   ├── components/           # React components
│   │   ├── TourProvider.tsx
│   │   ├── TourMachineReact.tsx
│   │   ├── TourOverlay.tsx
│   │   ├── DefaultCard.tsx
│   │   ├── DebugPanel.tsx
│   │   └── TourConfigViewer.tsx
│   ├── helpers/              # Utility functions
│   │   └── tourMachineGenerator.ts
│   ├── hooks/                # React hooks
│   │   └── useTour.ts
│   ├── types/                # TypeScript definitions
│   │   └── index.ts
│   ├── const.ts              # Constants
│   └── index.ts              # Main exports
├── dist/                     # Built files (git-ignored)
├── docs/                     # GitBook documentation
├── scripts/                  # Build scripts
│   └── setup-dev.sh
├── .learnings/               # Development notes
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

Link Not Working

If the linked package isn't recognized:

1. Verify global link exists:

   pnpm list -g --depth=0

2. Unlink and relink:

   # In library (tourista)
   pnpm run unlink
   pnpm run link
   
   # In test project
   pnpm unlink tourista --global
   pnpm link tourista --global

3. Note the package name difference:

   • Published package: Tourista

   • Local development link: tourista

Build Errors

If build fails:

1. Clear the dist folder:

   rm -rf dist

2. Rebuild:

   pnpm run build

Type Errors in Test Project

Ensure TypeScript server is restarted in your IDE after linking.

Hot Reload Not Working

If changes aren't reflected:

1. Ensure dev mode is running: pnpm run dev

2. Check that the link is active

3. Restart your Next.js dev server

Git Hooks

The project uses Husky for Git hooks. Run pnpm run prepare to set them up.

Next Steps

• Read the Architecture guide to understand the codebase

• Check Code Style for coding standards

• See Pull Requests for contribution guidelines