Contributing to Guccho

Learn how to set up your development environment and contribute to Guccho

Guccho is built with Nuxt 3 and TypeScript. This guide will help you get started with local development and contributing to the project.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: Version 22.17.1 or higher
• pnpm: Version 9.15.1 (package manager)
• A compatible platform (Linux, macOS, or Windows with WSL)

Development Setup

1. Clone the repository

   Clone the Guccho repository to your local machine:

   git clone https://github.com/ppy-sb/guccho.git
   cd guccho
   
2. Install dependencies

   Install all project dependencies using pnpm:

   pnpm install
   

   This will also run postinstall hooks that generate necessary files and prepare the Nuxt environment.

3. Configure the application

   Set up your configuration files:

   1. Create UI configuration:

      cp guccho.ui.config.example.ts guccho.ui.config.ts
      

   2. Create backend configuration:

      cp guccho.backend.config.example.ts guccho.backend.config.ts
      

   3. Set up environment variables:

      cp .env.example .env
      

   4. Edit these files according to the inline comments and your setup requirements.

4. Set up database tooling (optional)

   If you’re working with bancho.py or [e-mail], set the DB_DSN environment variable in your .env file to enable Drizzle ORM tooling.

Development Workflow

Running the Development Server

Start the development server with hot module replacement:

pnpm dev

The application will be available at http://localhost:3000.

Available Scripts

Here are the key npm scripts you’ll use during development:

Script	Command	Description
Development	pnpm dev	Start the development server at localhost:3000
Build	pnpm build	Build the application for production
Build All	pnpm build:all	Run build generators and build the app
Type Check	pnpm typecheck	Run TypeScript type checking with Nuxt
Lint	pnpm lint	Run ESLint on all source files
Lint Fix	pnpm lint:fix	Automatically fix linting issues
Analyze	pnpm analyze	Analyze bundle size and composition
Generate	pnpm generate	Generate static site

Code Quality

Linting

Guccho uses ESLint with the following configuration:

• Base config: @antfu/eslint-config
• Vue plugin: Follows Vue 3 recommended rules
• TypeScript: Strict type checking with inline type imports

Run the linter before committing:

pnpm lint

Automatically fix issues:

pnpm lint:fix

Type Checking

Always run type checking to catch TypeScript errors:

pnpm typecheck

Type checking is essential before submitting a pull request. The CI pipeline will fail if type errors are present.

Building for Production

To build the application for production:

pnpm build:all

This command:

1. Generates highlight.js configurations (build:hljs)
2. Runs other build generators (build:gen)
3. Builds the Nuxt application (build)

To test the production build locally:

pnpm start:prod

Contributing Guidelines

Code Style

Guccho follows these coding conventions:

• TypeScript: Always use TypeScript, never plain JavaScript
• Type imports: Use inline type imports (import type { Type } from 'module')
• Trailing commas: Required for multi-line arrays, objects, imports, and exports
• Curly braces: Use multi-line style for consistency
• Vue components: Single-word component names are allowed (non-standard)

Commit Messages

Write clear, descriptive commit messages:

• Use present tense (“Add feature” not “Added feature”)
• Be concise but descriptive
• Reference issue numbers when applicable

Pull Request Process

1. Create a feature branch from main
2. Make your changes following the code style guidelines
3. Run quality checks:
   pnpm lint
   pnpm typecheck
   pnpm build:all
   
4. Test your changes thoroughly
5. Commit your changes with clear messages
6. Push to your fork and create a pull request
7. Address review feedback if requested

Testing Your Changes

Before submitting a pull request:

Development Testing

1. Start the dev server: pnpm dev
2. Test all affected functionality
3. Check for console errors
4. Test in different viewports (mobile, tablet, desktop)

Production Testing

1. Build the application: pnpm build:all
2. Run the production server: pnpm start:prod
3. Verify functionality works in production mode
4. Check bundle size if you added dependencies: pnpm analyze

Code Quality

1. Run linter: pnpm lint
2. Fix issues: pnpm lint:fix
3. Type check: pnpm typecheck
4. Ensure all checks pass

Project Structure

The main development happens in these directories:

src/
├── components/      # Vue components
├── pages/          # Nuxt pages (file-based routing)
├── composables/    # Vue composables
├── server/         # Server-side code
│   └── backend/    # Backend implementations
├── def/            # Type definitions
└── assets/         # Static assets

Getting Help

If you need help:

• Check the GitHub Issues for existing questions
• Open a new issue for bugs or feature requests
• Join the ppy.sb community for discussions

License

By contributing to Guccho, you agree that your contributions will be licensed under the same license as the project.