Skip to main content
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 ppy.sb@bancho.py, 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:
ScriptCommandDescription
Developmentpnpm devStart the development server at localhost:3000
Buildpnpm buildBuild the application for production
Build Allpnpm build:allRun build generators and build the app
Type Checkpnpm typecheckRun TypeScript type checking with Nuxt
Lintpnpm lintRun ESLint on all source files
Lint Fixpnpm lint:fixAutomatically fix linting issues
Analyzepnpm analyzeAnalyze bundle size and composition
Generatepnpm generateGenerate 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:
  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)

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us