Skip to main content

Development Setup

This project uses a Python/FastAPI backend and a JavaScript frontend with a full build system. To contribute or modify the code, you will need both Python and a Node.js-compatible runtime like Node.js or Bun.

Prerequisites​

  • Python 3.8+ and uv.
  • Node.js & npm or Bun.

1. Clone the Repository​

git clone https://github.com/D221/vocaloid-rate
cd vocaloid-rate

2. Install Dependencies​

First, create a Python virtual environment and install the required packages.

# Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install uv (Windows)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install Python packages
uv sync

Next, install the Node.js development dependencies. This will also set up the pre-commit hooks via Husky.

# Using Bun (recommended)
bun install

# Or using npm
npm install

3. Running the Development Environment​

The development environment requires three processes to run concurrently: the FastAPI server, the Tailwind CSS compiler, and the JavaScript minifier. The project is configured to handle all of this with a single command.

Open your terminal and run:

# Standard dev mode (uses environment variables)
bun run dev

# Or force local SQLite mode (ignores DATABASE_URL)
bun run dev:local

This command uses concurrently to:

  1. Start the FastAPI backend server with hot-reloading.
  2. Start the Tailwind compiler in watch mode, which automatically builds and minifies app.css on any change.
  3. Start a file watcher (chokidar) that automatically runs terser to build and minify all *.min.js files whenever you save a source .js file.

Once running, access the application at http://localhost:8000. You can now edit your source .py, .js, and input.css files, and all changes will be reflected automatically.

4. Code Formatting and Linting​

This project uses Prettier, ESLint, and Ruff to ensure a consistent code style. These are configured to run automatically before each commit using Husky and lint-staged.

You can also run them manually:

  • Format all files: bun run format
  • Check for linting errors: bun run lint
  • Attempt to automatically fix linting errors: bun run lint:fix