HackJS

This is an image of a hacksaw

A fullstack JavaScript/TypeScript monorepo template for rapidly building Web and Mobile MVPs using modern tools. It bridges Next.js on the web and React Native (Expo) on mobile, connected via end-to-end type-safe RPC (Elysia + Eden Treaty).

Note

This template is designed for MVPs and prototyping — it prioritizes developer velocity over production-grade hardening. Use it as a starting point to validate ideas quickly, then harden as needed.

For those seeking a more comprehensive and production-hardened template, consider Better T-Stack.

Quick Start Tutorial

Learn how to build with HackJS by following the Quick Start Tutorial.

Core Stack

• Monorepo: Turborepo & Bun Workspaces — Efficient management of shared packages and apps with high-performance dependency resolution.
• Web App: Next.js (App Router) — Modern React framework optimized for performance, SEO, and developer productivity.
• Mobile App: React Native (Expo Router) — Native mobile development with shared logic and file-based routing.
• Database & ORM: Drizzle ORM + SQLite — Lightweight, local-first database with a type-safe, developer-friendly ORM.
• Authentication: Better Auth — A comprehensive authentication framework designed for safety and ease of integration.
• Communication: Elysia + Eden Treaty — High-performance, Bun-native RPC for seamless, end-to-end type safety between services.
• API Documentation: OpenAPI & Scalar — Automatically generated API schema and a beautiful developer-friendly reference UI.
• State Management: TanStack Query & nuqs — Robust server-state synchronization and type-safe URL search params.
• Validation: Zod & drizzle-zod — Schema-first validation for runtime safety and database schema inference.
• UI & Styling: Tailwind CSS & shadcn/ui — Utility-first styling with high-quality, accessible component primitives.
• Linting & Formatting: Biome — Ultra-fast, unified toolchain for maintaining code quality and consistent formatting.

Project Structure

.
├── apps/
│   ├── web/                     # Next.js App Router (Dashboard & API)
│   └── mobile/                  # React Native / Expo (Native Client)
├── packages/
│   ├── api/                     # Elysia API (End-to-end type-safety bridge)
│   ├── auth/                    # Better Auth (Authentication logic)
│   ├── db/                      # Drizzle ORM + SQLite (Database layer)
│   ├── types/                   # Shared TypeScript interfaces
│   ├── ui/                      # Shared UI system (Tailwind & Components)
│   ├── validators/              # Common Zod schemas
│   ├── utils/                   # Shared helper functions
│   └── assets/                  # Shared images and icons
└── package.json                 # Monorepo root & scripts

Setup

Prerequisites

• Bun (latest version)
• Node.js (v20+ recommended)
• ADB (for Android development)

1. Installation

git clone https://github.com/karume-lab/HackJS.git
cd HackJS
bun install

2. Environment Variables

Each app and package may require environment variables. Copy the .env.example files to .env in the following locations:

• .env
• apps/web/.env
• apps/mobile/.env

3. Database Initialization

Push your schema to the database and start the database studio:

# Push schema changes
bun db:push

# Generate migrations
bun db:generate

# Open Drizzle Studio to inspect data
bun db:studio

# Seed the database
bun db:seed

Usage

Development

Start all dev servers (Next.js + Expo) in parallel:

bun dev

Or run individual apps:

# Web only (Next.js)
bun dev:web

# Mobile only (Expo)
bun dev:mobile

Mobile Specifics

# Android emulator/device
bun android:mobile

# iOS simulator
bun ios:mobile

# Get local IP (for mobile connection)
bun get-ip:mobile

# Check mobile environment health
bun doctor:mobile

API Documentation

The API documentation is automatically generated from your Elysia routes using the Swagger plugin. HackJS uses Fumadocs for a beautiful, interactive documentation experience.

• OpenAPI Schema: http://localhost:3000/api/openapi.json
• Interactive Reference: http://localhost:3000/docs/api/reference

Documentation & ADRs

HackJS maintains Architecture Decision Records (ADRs) to document key technical decisions. These can be found in the /docs directory:

• ADR 001: Elysia for Type Safety
• ADR 002: Better Auth
• ADR 003: Drizzle ORM
• ADR 004: Turborepo & Bun
• ADR 005: Next.js App Router
• ADR 006: Expo Router
• ADR 007: Scalar & OpenAPI
• ADR 008: State Management
• ADR 009: Zod Validation
• ADR 010: UI Architecture
• ADR 011: Biome

Explore the /docs folder for more detailed architectural insights.

Adding New Features

New API Procedure

1. Define your Zod schema in packages/validators.
2. Implement the procedure in packages/api/src/routers/.
3. The type-safe client will be automatically available to both web and mobile.

New UI Component

# Web (shadcn/ui)
bun ui:web [component-name]

# Mobile (react-native-reusables)
bun ui:mobile [component-name]

Code Quality

Run checks across the entire monorepo:

# Format and lint fix all apps and packages
bun clean

# Run linter checks
bun lint

# Run type checks
bun typecheck

Or target specific apps:

# Lint web app only
bun lint:web

# Typecheck mobile app only
bun typecheck:mobile

Available Scripts

Script	Description
bun dev	Start all apps in watch mode
bun build	Build all apps and packages
bun lint	Lint all apps and packages
bun typecheck	Typecheck all apps and packages
bun clean	Fix linting/formatting issues across the repo
Web App
bun dev:web	Start Next.js development server
bun build:web	Build Next.js for production
bun lint:web	Lint web app
Mobile App
bun dev:mobile	Start Expo development server
bun android:mobile	Run on Android
bun ios:mobile	Run on iOS
bun doctor:mobile	Run Expo doctor
Database
bun db:push	Push schema to database
bun db:generate	Generate migration files
bun db:studio	Open Drizzle Studio
bun db:seed	Seed the database

Deployment

Web (Next.js)

Deploy to Vercel by connecting your repository. Ensure you set all environment variables in the Vercel dashboard.

Mobile (React Native)

Use Expo Application Services (EAS) for builds and submissions:

# Login to Expo
bunx eas login

# Build for Android
bunx eas build -p android

# Build for iOS
bunx eas build -p ios

Contributing

Contributions are welcome! Please read our CONTRIBUTING.md and CODE_OF_CONDUCT.md before getting started.

1. Create a Branch: Create a new branch for your changes (git checkout -b feature/[FEATURE_NAME]).
2. Make Changes: Implement your changes and ensure they follow the project's coding standards.
3. Run Tests: Ensure all tests pass (bun lint and bun typecheck).
4. Submit a Pull Request: Submit a pull request to the main repository.

---

Thank you for your interest in HackJS and remember to star the repo!