NOTE: This project was 100% vive coded. It was built to meet our own needs for a feature-rich, user-friendly open source expense splitting app. It works reliably for us and we use it daily, but we do not plan to refactor it. It fulfills its intended purpose as-is.
Kostos makes it easy for groups to track, manage, and split expenses together. No user registration is required. A simple interface with powerful features designed for effortless collaboration.
- Project Management: Create new projects or join existing ones to manage shared expenses.
- Member Management: Add members to projects.
- No user accounts required: Uses unique user and project IDs, your session is stored in your browser local storage.
- Expense Tracking: Record expenses with details like description, amount, date, category, and payment method.
- Flexible Splitting: Split expenses evenly, by specific amounts (supports basic math expressions!) or by shares.
- Payment Tracking: Record which member(s) paid for each expense. Support multiple payers.
- Category Management: Create custom categories with names and colors to organize expenses.
- Payment Method Management: Define and track custom payment methods with names and icons.
- Statistics: Visualize project expense data with beautiful charts.
- Data Import/Export: Functionality to import/export project data (uses Spliit format).
- Progressive Web App (PWA): Configured for PWA capabilities via
next-pwa
. - Dockerized: Includes
Dockerfile
andcompose.yaml
for easy deployment.
-
Get the docker compose file
wget -O docker-compose.yml https://raw.githubusercontent.com/shynewt/kostos/refs/heads/main/compose.yaml
-
Run
# The sqlite file must exist before running touch kostos.db && docker compose up -d
-
Open http://localhost:3000 in your browser
-
Clone the repository:
git clone <repository-url> cd kostos
-
Install dependencies:
npm install
-
Set up the database:
-
Run all migrations (creates the database if it doesn't exist):
npm run db:migrate
-
(Optional) Seed initial data if needed (check
scripts/init-db.js
):npm run db:init
-
-
Run the development server:
npm run dev
Open http://localhost:3000 in your browser.
npm run dev
: Starts the Next.js development server.npm run build
: Builds the application for production.npm run start
: Starts the production server (requiresbuild
first).npm run lint
: Runs Next.js's built-in linter.npm run db:generate
: Generates SQL migration files based on schema changes using Drizzle Kit.npm run db:migrate
: Applies all pending migrations to the database using Drizzle Kit.npm run db:push
: Pushes schema changes directly to the database (useful for rapid prototyping, potentially destructive).npm run db:studio
: Opens Drizzle Studio, a GUI for interacting with the database.npm run db:init
: Runs a script to potentially initialize/seed the database (seescripts/init-db.js
).npm run db:pull
: Introspects the current database schema and updatesdb/schema.ts
.
This project uses Drizzle ORM to manage the SQLite database schema and queries.
- Schema: Defined in
db/schema.ts
. - Migrations: Managed by Drizzle Kit. Generate new migrations using
npm run db:generate
after changing the schema. Apply migrations usingnpm run db:migrate
.
- The Docker image uses an entrypoint script that ensures the database file exists and runs all migrations before starting the app.
- You do not need to manually create the database file; it will be created automatically.
- On container startup, migrations are always applied to keep the schema up to date.
- Framework: Next.js
- Language: TypeScript
- UI Library: React
- Styling: Tailwind CSS
- Database: SQLite
- ORM: Drizzle ORM
- Charting: Chart.js / react-chartjs-2
- Date Handling: date-fns