Habitrack

               

Habitrack is a simple and intuitive web app designed for logging habits and v isualizing them on a calendar view.

This app showcases the use of the following tools and technologies:

• React 19.3 with TypeScript 6, bundled with Vite 8
• React Router v8 in framework mode for routing, data loading and mutations (loaders, actions, fetchers)
• Zustand v5 for client-side UI state
• Tailwind CSS v4 for styling
• HeroUI for the UI components
• React Aria calendar hooks to generate the calendar view
• Supabase for Authentication, Database and Storage
• Vitest and React Testing Library for unit-testing
• ESLint, Prettier, Husky, and SQLFluff for linting and formatting
• Docker for running a local Supabase instance
• GitHub Actions for CI/CD and Vercel for deployment

Features

• Customizable Habits: Add, remove, and customize habits to fit your routine. Associate your habits with traits and icons.
• Calendar View: Visualize your habits on a monthly calendar.
• Daily Tracking: Easily add daily entries of your habits.
• Habit Streaks: Track your habit streaks and stay motivated.
• Habit Stocks: Maintain a stock count for habits that require consumable resources.
• Habit Spending: Track spending related to habits.
• User Authentication: Sign up and log in to your account to retain your habits and entries.'
• Responsive Design: Enjoy a seamless experience on any device.
• PWA: Install the app on your device for quick access.

Roadmap

• Dark Mode: Switch between light and dark themes.
• Weekly View: View your habits on a weekly calendar.
• Daily View: Dive into your habits on a daily calendar.
• Export: Export your habits and entries.
• Categories: Group habits into categories.
• Environments: Associate habits with environments where they occur.
• Habit Stocks: Maintain a stock count for habits that require consumable resources.
• Habit Spending: Track spending related to habits.
• Habit Presets: Use predefined habit templates for quick setup.
• Log Presets: Create and use log entry presets for faster logging.
• Statistics: Track your progress with insightful statistics.
• Enriched Habit Streaks: Extended options to visualize and track habit streaks (basic one-off streaks are displayed under /habits).
• Sharing: Share your calendar with trusted people.
• Group Calendars: Form or break habits together with friends or under a supervision of a coach.
• Group Challenges: Participate in habit challenges within groups.
• Notifications: Get reminders to log your habits via PWA notifications and later via email.
• Offline Support: Use the app without an internet connection.

There's also a public roadmap on Featurebase where you can upvote and suggest new features: Habitrack Public Roadmap.

Tech Debt

• Migrate to Vitest: Replace Jest with Vitest.
• Migrate to ESLint v9: Update to ESLint v9 and use flat config.
• Migrate to HeroUI 3: Update to HeroUI v3 (currently in beta) once it reaches stable release.

Local development

Prerequisites

• Git
• Node.js (24.22.1)
• Docker
• Yarn is used as a package manager and is automatically available via Corepack (bundled with Node.js)

Initial Setup

Follow these steps to get the project up and running on your local machine.

1. Clone the repository:

   git clone https://github.com/domhhv/habitrack.git
   

2. Navigate to the project directory:

   cd habitrack
   

3. Install dependencies:

   yarn install
   

Local Database Setup

The project uses Supabase for database operations.

The Supabase project configuration, seeds, and migrations live under the supabase directory.

To set up a local Supabase instance, run the following commands (Docker required).

1. Start the local Supabase instance:

   yarn db:start
   

   This command starts Supabase Docker containers based on supabase/config.toml and creates a local Postgres database and services.

   It should output the Studio URL, Database URL, and Project URL, among other info. Use the Studio URL to access the local Supabase dashboard in the browser, and the Database URL to connect to the local database directly if needed.

2. Retrieve the API URL and keys:

   Run the following command to retrieve the API URL and keys for the local Supabase instance:

   yarn db:status -o env
   

   This command outputs the environment variables needed to connect to the local Supabase instance, including API_URL, PUBLISHABLE_KEY and SECRET_KEY.

3. Environment variables

   Create a .env.development file in the root directory of the project and add the following environment variables:

   SUPABASE_URL=<API_URL>
   SUPABASE_PUBLISHABLE_KEY=<PUBLISHABLE_KEY>
   SUPABASE_SECRET_KEY=<SECRET_KEY>
   

   The publishable key ships to the browser, and Row Level Security protects the data. The secret key bypasses Row Level Security, so only server-only code reads it. Nothing uses it yet, so it's optional for now.

4. Apply migrations and seed the database:

   yarn db:reset
   

   This command resets the local database to a clean state, applies migrations from supabase/migrations, and seeds the db with essential initial data based on supabase/seed.sql.

Run the app

Once the dependencies are installed and the local Supabase instance is running, you can run the app locally:

yarn dev

This command starts the development server and opens the app in your default browser.

Database Migrations

There are a few ways to create and run migrations in the project.

• [Recommended] Change or create declarative database schema SQL files under supabase/schemas directory as needed

This project uses declarative database schema management, so the preferred way to make changes to the database schema is to modify the SQL files under supabase/schemas directory.

If you need to modify an existing table, add a new table/type/function, or make any other schema changes, do so by editing or adding SQL files in the supabase/schemas directory, then run:

yarn db:diff -f <your-migration-name>

• Diffing the Supabase Studio database schema changes to automatically generate a new migration file

Do the necessary changes in the local Supabase studio and then run the following to automatically generate a new migration file:

yarn db:diff -f <your-migration-name>

• Creating a new migration file manually

To create a new migration file manually, run the following command:

yarn db:migration:new <your-migration-name>

---

Either way, the new migration file will be created in the supabase/migrations directory. Write/change the SQL queries in the migration file to reflect the changes you want to make to the database schema. Then, apply the migration by running:

yarn db:migration:up # or
yarn db:reset # to reset the local DB and apply all migrations

After applying the migration, you also need to regenerate Supabase types by running:

yarn db:gen-types

Once the migration ends up in the main branch, it will be automatically applied to the production database.

Important step: After applying any new migrations, always remember to regenerate Supabase types by running yarn db:gen-types to keep the types in sync with the database schema.

Testing

The project uses Vitest as the test runner and React Testing Library for unit testing of React components.

To run the tests, use the following command:

yarn test

Other test-related commands include:

yarn test:coverage # Run all tests and generate coverage report
yarn test:watch # Run all tests in watch mode
yarn test:no-cache # Run all tests without cache

Linting

There are two types of linting in the project: JavaScript/TypeScript linting and SQL linting.

JS/TS

The project uses ESLint v10 with a custom flat config for linting. To run ESLint, use the following command:

yarn eslint:check # Check for linting errors
yarn eslint:fix # Fix linting errors

SQL

In addition to ESLint, the project uses SQLFluff for linting SQL queries under supabase directory. To run SQLFluff (Docker required), use the following command:

yarn lint:sql # Lint SQL queries
yarn fix:sql # Find fixable linting violations in SQL queries and apply fixes

Formatting

The project uses Prettier for formatting. To run Prettier, use the following command:

yarn prettier:check # Check for formatting errors
yarn prettier:write # Fix formatting errors

Building

To create a local production-like build of the app, run the following command:

yarn build

You can run the production build locally using the following command:

yarn preview

CI/CD

The project uses GitHub Actions for CI/CD.

Pull Requests

When you open a pull request, the following checks are run:

• Setup: Install and cache Yarn dependencies.
• Typecheck: Run TypeScript type checks.
• ESLint: Run ESLint checks for JS/TS lint issues.
• SQLFluff: Run SQLFluff checks for SQL lint issues.
• Prettier: Run Prettier checks for formatting issues.
• Unit tests: Run unit tests with Vitest (currently not required to pass as tests are incomplete).
• RelativeCI: Visual regression tests powered by RelativeCI.
• Deploy preview: Build and deploy the app to Vercel for preview.
• Coderabbit PR Review: Automated code review powered by CodeRabbit.

All checks but the last one must pass before merging a pull request.

Merging to Main

When a pull request is merged to the main branch, the following checks are run:

• Deploy app: Build and deploy the app to Vercel.
• Migrate database: Apply Supabase migrations to the production database, if any.

Contributing

Contributions are welcome! Feel free to open issues or pull requests for any improvements, bug fixes, or new features.