Contributing to Hollama

We welcome contributions to Hollama! Whether you've found a bug, have a feature request, or want to submit code, this guide will help you get started.

How to Contribute

  • Found a bug or have a feature request?
    1. Search the existing issues to see if it has already been reported.
    2. If not, open a new issue.
  • Comment or upvote on existing issues. Active issues are more likely to be prioritized.
  • Submit a pull request. Please discuss your proposed changes in an issue first to ensure they align with the project's goals.

Development Setup

Hollama is a static site built with SvelteKit, TypeScript, and Tailwind CSS. It also includes an Electron wrapper for the desktop application.

Prerequisites

  • Node.js (version specified in .nvmrc, currently v22)
  • npm

Installation

  1. Clone the repository: 

    git clone https://github.com/fmaclen/hollama.git
cd hollama

  2. Install dependencies: 

    npm install

Running the Development Server

To start the Vite development server for the web application:

npm run dev

# Or to open the app in a new browser tab automatically:
npm run dev -- --open

This will start the app, typically on http://localhost:5173.

Running the Electron App

To run the application in development mode within the Electron shell:

npm run electron

This will launch the Electron window, which loads the content from the running Vite dev server.

Building for Production

Web Application

To create a production-ready build of the SvelteKit web app:

npm run build

This command generates optimized static files in the .svelte-kit directory, tailored for the configured adapter (e.g., Node.js or Cloudflare Pages). You can preview the production build locally with npm run preview.

Desktop Application

To build and package the Electron desktop application for your current operating system:

npm run electron:build

This script first runs vite build with the correct environment, then uses electron-builder to package the app into distributable formats (e.g., .dmg, .exe) in the dist/ directory.

Testing

Hollama uses Playwright for end-to-end integration testing. Tests are located in the tests/ directory.

To run the test suite:

npm run test

This command will build the application, start a preview server, and run the Playwright tests against it.

Linting and Formatting

We use ESLint for linting and Prettier for code formatting to maintain a consistent codebase.

  • Check for issues: 

    npm run lint

  • Automatically format files: 

    npm run format

The CI pipeline will run the lint command, so it's a good idea to run it locally before committing.

CI/CD Pipeline

Our continuous integration and deployment process is managed by GitHub Actions, with workflows defined in .github/workflows/:

  • lint.yml: Runs ESLint on every pull request.
  • test.yml: Runs the Playwright test suite on every pull request.
  • versioning.yml: Uses semantic-release to automatically determine the next version number, create a GitHub release, and update package.json based on conventional commit messages.
  • build.yml: Triggered after a successful release. It builds and publishes the live demo to Cloudflare Pages, the desktop apps to GitHub Releases, and the Docker image to GitHub Container Registry.