Quick Start for Developers

This guide will help you set up your development environment and start working on the FiNAN website within minutes.

Prerequisites

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

Required Software

Node.js - Version 18.x or higher
- Download from nodejs.org
- Verify installation: node --version
npm - Comes with Node.js
- Package manager for JavaScript
- Verify installation: npm --version
Git - Version control system
- Download from git-scm.com
- Verify installation: git --version

Recommended Tools

VS Code - Recommended code editor with excellent Astro support
- Install the Astro extension
- Install the Tailwind CSS IntelliSense extension
- Install the Prettier extension
- Install the ESLint extension
Terminal - Use your preferred terminal (Terminal, iTerm2, Git Bash, etc.)

Installation

Clone the Repository

# Clone the repository
git clone https://github.com/poncardasm/finan-website.git

# Navigate to the project directory
cd finan-website

Install Dependencies

The project uses npm for package management. Install all dependencies:
Terminal window
```
npm install
```
This will install:
- Astro 5.15.9
- Tailwind CSS 4.1.13
- TypeScript 5.9.2
- Ghost CMS client
- PhotoSwipe
- All development tools (ESLint, Prettier, etc.)
Environment Variables (Optional)

If you need to work with the Ghost CMS integration, create a .env file in the root directory:
.env
```
GHOST_URL=https://puls.finan.eu.com
GHOST_CONTENT_API_KEY=your_api_key_here
```
Note: The Ghost CMS integration will gracefully degrade if environment variables are not set, so this is optional for most development work.
Start the Development Server
Terminal window
```
npm run dev
```
This will start the Astro development server at http://localhost:4321. The server supports:
- Hot module replacement (HMR) - Changes appear instantly
- Fast refresh - Component updates without full page reload
- TypeScript type checking
- Astro island hydration
Open your browser and navigate to http://localhost:4321 to see the site.

Development Workflow

Daily Development Commands

Command	Description
`npm run dev`	Start development server at localhost:4321
`npm run build`	Build production site to ./dist/
`npm run preview`	Preview built site locally
`npm run lint`	Run ESLint on codebase
`npm run lint:fix`	Run ESLint with auto-fix
`npm run format`	Format code with Prettier
`npm run format:check`	Check code formatting
`npm run astro`	Run Astro CLI commands

Recommended Development Flow

Start the dev server:
Terminal window
```
npm run dev
```
Make your changes to components, pages, or data files
Check the browser - Changes should appear automatically
Before committing, run code quality checks:
Terminal window
```
npm run lint:fix && npm run format
```
Test the production build:
Terminal window
```
npm run build
npm run preview
```
Commit your changes with clear, descriptive commit messages

Project Structure Quick Reference

Here’s what you’ll be working with most often:

finan-website/
├── src/
│   ├── components/        # 25 reusable Astro components
│   │   ├── Navbar.astro
│   │   ├── Footer.astro
│   │   ├── Committee.astro
│   │   └── ...
│   ├── pages/             # File-based routing
│   │   ├── index.astro    # Home page
│   │   ├── about.astro
│   │   ├── representation/
│   │   │   ├── finland.astro
│   │   │   ├── sweden.astro
│   │   │   └── ...
│   │   └── ...
│   ├── data/              # Type-safe data configurations
│   │   ├── siteConfig.ts
│   │   ├── representation/
│   │   │   ├── committee/
│   │   │   ├── partnership/
│   │   │   └── publication/
│   │   └── pages/
│   ├── assets/            # Optimized images
│   │   └── images/
│   │       ├── committee/
│   │       ├── events/
│   │       └── gallery/
│   ├── layouts/           # Page layout templates
│   ├── scripts/           # Client-side JavaScript
│   └── styles/            # Global CSS
├── public/                # Static assets (served as-is)
│   ├── flags/
│   ├── icons/
│   └── images/
├── astro.config.mjs       # Astro configuration
├── tailwind.config.js     # Tailwind CSS configuration
├── tsconfig.json          # TypeScript configuration
└── package.json           # Dependencies and scripts

For a detailed breakdown, see Project Structure.

Making Your First Change

Let’s make a simple change to verify everything is working:

Example 1: Update a Text String

Open src/pages/index.astro
Find the hero section text
Make a small change to any heading or paragraph
Save the file
Check your browser - the change should appear instantly

Example 2: Modify a Component

Open src/components/Footer.astro
Update the footer text or add a link
Save the file
Check your browser - all pages with the footer will update

Example 3: Add a FAQ Item

Open src/data/pages/faq/faqData.ts

Add a new FAQ object to the appropriate category array:

{
  question: 'Your new question?',
  answer: 'Your answer here.',
}

Save the file
Navigate to /faq in your browser to see the new item

Understanding Key Concepts

Astro Islands Architecture

Astro uses “islands architecture” where:

Most of the site is static HTML (fast and SEO-friendly)
Interactive components are “hydrated” only when needed
JavaScript is minimal by default

Type-Safe Data Layer

All data configurations use TypeScript:

Interfaces ensure data structure consistency
Auto-completion in your IDE
Compile-time error checking
as const satisfies pattern for type safety

Example:

import type { CommitteeMember } from './types';

export const finlandCommittee = [
  {
    name: 'John Doe',
    role: 'Country Representative',
    email: 'john@example.com',
    image: johnDoeImage,
  },
] as const satisfies readonly CommitteeMember[];

Component-Driven Design

The site is built from reusable components:

Each component handles a specific UI concern
Props are TypeScript-typed
Components are composable and reusable
Styling uses Tailwind CSS utilities

Code Quality Standards

The project enforces code quality through:

ESLint

Checks for code issues and potential bugs
Enforces consistent code patterns
Astro-specific linting rules
Run with: npm run lint

Prettier

Formats code consistently
Sorts Tailwind CSS classes automatically
Astro-specific formatting
Run with: npm run format

TypeScript

Type checking at build time
Interfaces for all data structures
Strict type safety enabled

Important: Pre-Commit Workflow

Always run this before committing:

npm run lint:fix && npm run format

This ensures:

ESLint rules are enforced and auto-fixed
Code formatting is consistent
Tailwind classes are sorted
No linting errors in commits

Working with Different File Types

`.astro` Files

Astro component files with three sections:

--- frontmatter (TypeScript)
HTML-like template
Optional <script> and <style> tags

`.ts` Files

TypeScript configuration and data files:

Type definitions in types.ts files
Data configurations with as const satisfies
Utilities and helper functions

`.css` Files

Styling with Tailwind:

Global styles in src/styles/
Utility-first approach
Custom CSS when needed

Next Steps

Now that you have your environment set up:

Explore the codebase - Browse through components and pages
Read the architecture guide - Architecture Overview
Learn about components - Component Architecture
Understand data patterns - Data Configuration
Review code quality - Development Workflow

Common Issues

Port Already in Use

If port 4321 is already in use:

# Kill the process using port 4321 (macOS/Linux)
lsof -ti:4321 | xargs kill -9

# Or use a different port
npm run dev -- --port 3000

TypeScript Errors

If you see TypeScript errors:

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

Build Failures

Check for:

TypeScript type errors
Missing imports
Incorrect file paths
Image import issues

See Troubleshooting for more help.

Getting Help

If you encounter issues:

Check this documentation - Use the search feature
Review error messages - They often point to the solution
Check the troubleshooting guide - Common Issues
Ask the team - Reach out via GitHub issues

Happy coding!