Installation Guide

Prerequisites

Before you begin, ensure you have the following installed on your system:

Required Software

Node.js 18 or higher

Chapinismos requires Node.js version 18.0.0 or higher. Check your version:

node --version

Installation:

macOS: brew install node or download from nodejs.org
Windows: Download installer from nodejs.org
Linux: Use your package manager (e.g., apt install nodejs or dnf install nodejs)

We recommend using nvm (Node Version Manager) to manage multiple Node.js versions on your system.

Package Manager (pnpm, npm, or yarn)

The project supports multiple package managers. Choose one:pnpm (Recommended - faster and more efficient):

npm install -g pnpm

npm (Comes with Node.js):

npm --version

yarn (Alternative):

npm install -g yarn

The examples in this documentation use pnpm, but you can substitute it with npm or yarn in any command.

Git

Git is required to clone the repository and manage version control.

git --version

Installation:

macOS: brew install git or included with Xcode Command Line Tools
Windows: Download from git-scm.com
Linux: Use your package manager (e.g., apt install git)

Recommended Tools

VS Code

Recommended editor with excellent Astro support and extension ecosystem

Astro VS Code Extension

Provides syntax highlighting, IntelliSense, and error checking for .astro files

Prettier Extension

Automatic code formatting on save for consistent code style

ESLint Extension

Real-time linting and error detection in your editor

Installation Steps

Clone the repository

Open your terminal and clone the Chapinismos repository to your local machine:

git clone https://github.com/abisai7/diccionario-chapin.git
cd diccionario-chapin

If you plan to contribute, consider forking the repository first and cloning your fork instead:

git clone https://github.com/YOUR_USERNAME/diccionario-chapin.git

Install dependencies

Install all required packages using your preferred package manager:

pnpm install

This will install:

Astro 5.18+ - Core framework
Tailwind CSS 4.2+ - Styling framework
TypeScript - Type safety
ESLint & Prettier - Code quality tools
Zod - Schema validation
And other dependencies listed in package.json

Installation typically takes 1-3 minutes depending on your internet connection.

Verify the installation

Ensure everything installed correctly by checking the project structure:

ls -la

You should see:

node_modules/ directory (dependencies)
src/ directory (source code)
public/ directory (static assets)
package.json (project configuration)
astro.config.mjs (Astro configuration)
tsconfig.json (TypeScript configuration)

Start the development server

Launch the local development server:

pnpm run dev

You should see output similar to:

🚀 astro v5.18.0 started in 152ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose

Open your browser and navigate to http://localhost:4321 to view the site.

The development server supports hot module replacement (HMR), so changes you make to files will be reflected immediately in the browser without a full page reload.

Configure your editor (Optional but recommended)

If using VS Code, install the recommended extensions:

Open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
Type “Extensions: Show Recommended Extensions”
Install all workspace recommendations

Create or update .vscode/settings.json in the project root:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "[astro]": {
    "editor.defaultFormatter": "astro-build.astro-vscode"
  }
}

This enables automatic formatting and linting on save.

Project Configuration

After installation, you may want to review or customize these configuration files:

`astro.config.mjs`

Main Astro configuration including:

Site URL (https://chapinismos.org)
Output mode (static)
i18n settings (default locale: es, available: es, en)
Vercel adapter
Sitemap generation
Vite build optimizations

astro.config.mjs

import { defineConfig } from "astro/config";
import sitemap from "@astrojs/sitemap";
import vercel from "@astrojs/vercel";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  site: "https://chapinismos.org",
  output: "static",
  adapter: vercel(),
  i18n: {
    defaultLocale: "es",
    locales: ["es", "en"],
    routing: {
      prefixDefaultLocale: true,
    },
  },
  // ... more configuration
});

`package.json`

Available npm scripts:

Script	Command	Description
`dev`	`astro dev`	Start development server on port 4321
`start`	`astro dev`	Alias for `dev`
`build`	`astro build`	Build for production
`preview`	`astro preview`	Preview production build locally
`format`	`prettier --write .`	Format all files with Prettier
`format:check`	`prettier --check .`	Check formatting without modifying files
`lint`	`eslint .`	Lint code with ESLint
`lint:fix`	`eslint . --fix`	Auto-fix linting issues

`src/content/config.ts`

Content Collections schema defining the structure for word entries. This file uses Zod for runtime validation:

src/content/config.ts

import { defineCollection, z } from "astro:content";

const wordsSchema = z.object({
  word: z.string(),
  meaning: z.string(),
  examples: z.array(z.string()),
  category: z.enum([
    "sustantivo", "verbo", "adjetivo", "adverbio",
    "expresión", "interjección", "modismo",
    "noun", "verb", "adjective", "adverb",
    "expression", "interjection", "idiom",
  ]),
  region: z.string().optional(),
  synonyms: z.array(z.string()).optional(),
  relatedWords: z.array(z.string()).optional(),
  featured: z.boolean().optional(),
});

export const collections = {
  "words-es": defineCollection({ type: "content", schema: wordsSchema }),
  "words-en": defineCollection({ type: "content", schema: wordsSchema }),
};

Troubleshooting

Port 4321 is already in use

If port 4321 is occupied by another process, you can specify a different port:

pnpm run dev -- --port 3000

Or set the PORT environment variable:

PORT=3000 pnpm run dev

Module not found errors

If you encounter “Cannot find module” errors:

Delete node_modules/ and lock files:
```
rm -rf node_modules pnpm-lock.yaml
```

Clear package manager cache:

pnpm store prune  # for pnpm
npm cache clean --force  # for npm

Reinstall dependencies:
```
pnpm install
```

TypeScript errors in the editor

If VS Code shows TypeScript errors:

Ensure the Astro VS Code extension is installed
Restart the TypeScript server:
- Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
- Type “TypeScript: Restart TS Server”
Check that tsconfig.json exists in the project root

Prettier/ESLint not working

If automatic formatting or linting isn’t working:

Verify extensions are installed:
- Prettier - Code formatter
- ESLint
Check VS Code settings (.vscode/settings.json)
Run formatters manually to test:
```
pnpm run format
pnpm run lint
```

Content Collection build errors

If you see Zod validation errors during build:

[ERROR] "word" is required
[ERROR] "category" must be one of: sustantivo, verbo, ...

This means a word file in src/content/words-es/ or src/content/words-en/ has invalid frontmatter. Check the error message for the filename and verify all required fields are present.See the Validation Schema page for complete field requirements.

Environment Variables

Chapinismos doesn’t require environment variables for local development. All configuration is done through the astro.config.mjs file.

For production deployments, you may want to set:

PUBLIC_UMAMI_WEBSITE_ID - For analytics tracking (optional)
PUBLIC_SITE_URL - Override the default site URL

Next Steps

Now that you have the project installed locally, you’re ready to:

Add Your First Word

Learn how to create new word entries in the dictionary

Explore the Architecture

Understand how the project is organized and structured

Customize the Design

Modify colors, fonts, and layouts to match your preferences

Development Workflow

Learn about hot reload, debugging, and development tools

Having trouble? Check the GitHub Issues page or open a new issue for help.

Get Started

Content Management

Architecture

Features

Customization

Development

Contributing

Prerequisites

Required Software

Recommended Tools

VS Code

Astro VS Code Extension

Prettier Extension

ESLint Extension

Installation Steps

Project Configuration

`astro.config.mjs`

`package.json`

`src/content/config.ts`

Troubleshooting

Environment Variables

Next Steps

Add Your First Word

Explore the Architecture

Customize the Design

Development Workflow

Build docs developers (and LLMs) love

Get Started

Content Management

Architecture

Features

Customization

Development

Contributing

​Prerequisites

​Required Software

​Recommended Tools

VS Code

Astro VS Code Extension

Prettier Extension

ESLint Extension

​Installation Steps

​Project Configuration

​astro.config.mjs

​package.json

​src/content/config.ts

​Troubleshooting

​Environment Variables

​Next Steps

Add Your First Word

Explore the Architecture

Customize the Design

Development Workflow

Build docs developers (and LLMs) love

Prerequisites

Required Software

Recommended Tools

Installation Steps

Project Configuration

`astro.config.mjs`

`package.json`

`src/content/config.ts`

Troubleshooting

Environment Variables

Next Steps