Modern, open-source invoice generation platform built with Next.js, tRPC, and TypeScript.

For Cloudflare Workers hosting with OpenNext, follow the deployment guide, including staging validation and domain cutover.

• Node.js: Version 22.9.0 or higher
• Yarn: Version 4.9.1 or higher (automatically managed via packageManager field)
• PostgreSQL: Database for storing application data

1. Clone the repository

   git clone https://github.com/legions-developer/invoicely.git
   cd invoicely

2. Install dependencies

   yarn install

3. Set up environment variables

   # Create environment file in root directory
   cp .env.example .env
   
   # Create symlinks for environment variables across apps
   yarn sys-link

4. Set up the database

   # Generate database schema
   yarn db:generate
   
   # Run database migrations
   yarn db:migrate

5. Start development server

   yarn dev

Run yarn test:security to check dependency compatibility and the local patches. Run yarn npm audit --all --recursive --no-deprecations to check published vulnerability advisories across all workspaces.

The Yarn patch in .yarn/patches/braces-npm-3.0.3-security.patch mitigates GHSA-vfj7-8cjw-p6xm by rejecting brace/parenthesis and AST nesting beyond 100 levels. No upstream patched release is available as of October 5, 2026, so version-based scanners can still flag braces@3.0.3. Yarn's audit returns no advisories for this patched tree; that result must be paired with the patch regression tests. Keep the upstream warning visible and replace the patch with a fixed release when available.

The node-gyp resolution removes the vulnerable make-fetch-happen → http-cache-semantics dependency chain. Retain Node.js 22.9.0 or newer for this build tool.

The Sentry resolution pins @sentry/nextjs@10.76.0 to .yarn/patches/sentry-nextjs-npm-10.76.0-runtime.patch. Its server entry imports a build helper that eagerly calls createRequire(__filename); OpenNext's Worker bundle supplies an empty filename, causing instrumentation startup and auth requests to fail. The patch defers that call until the build helper is used. Remove the patch, resolution, and sentryRuntimePatch cache dependency in apps/web/next.config.ts when an upstream fix passes yarn test:security and auth requests against the built Worker, including /api/auth/ok and an unauthenticated /api/auth/get-session.

Open Dashboard in the sidebar to view local invoices and, when signed in, your saved server invoices. Select a currency to see collected, outstanding, and overdue totals, six- or twelve-month trends, and the top five clients by all-time billed amount. Currencies are never combined or converted.

• Collected includes invoices marked success. Monthly collections use the recorded payment date; paid invoices without one remain in all-time totals.
• Outstanding includes pending, error, and expired invoices. Overdue is the subset past its due date or marked expired; an invoice due today is not overdue.
• Refunded invoices are excluded from amounts. Monthly billed amounts use the invoice date, and clients are grouped by normalized name and address.
• Amounts use decimal arithmetic and round each invoice to two decimals, matching invoice display precision. Partial payments and a payment ledger are not supported.

The dashboard uses existing invoice fields and requires no new database migration, environment variable, or dependency.

• Next.js 15.3.1 - React framework with App Router
• React 19 - UI library
• TypeScript 5.8.2 - Type-safe JavaScript

• tRPC 11.1.2 - End-to-end type-safe APIs
• TanStack Query 5.76.1 - Server state management
• Jotai 2.12.3 - Atomic state management
• Zod 3.25.7 - Schema validation

• Tailwind CSS 4 - Utility-first CSS framework
• Radix UI - Headless UI components
• Shadcn/ui - Re-usable components built on Radix
• Lucide React - Icon library
• Motion 12.10.5 - Animation library
• Next Themes - Theme management

• Drizzle ORM 0.43.1 - Type-safe database ORM
• Neon Database - Serverless PostgreSQL
• Better Auth 1.2.8 - Modern authentication library
• Google OAuth - Social authentication

• Cloudflare R2 - Object storage
• React PDF 9.2.1 - PDF generation

• Turbo 2.5.3 - Monorepo build system
• ESLint 9 - Code linting
• Prettier 3.5.3 - Code formatting
• Husky 9.1.7 - Git hooks

• PostHog - Product analytics
• OpenPanel - Privacy-focused analytics
• React Scan - Performance debugging

• Date-fns 4.1.0 - Date manipulation
• Lodash 4.17.21 - Utility functions
• Decimal.js 10.5.0 - Arbitrary precision decimal arithmetic
• UUID 11.1.0 - Unique identifier generation

invoicely/
├── apps/
│   └── web/                    # Next.js web application
│       ├── src/
│       │   ├── app/           # App Router pages
│       │   ├── components/    # Reusable UI components
│       │   ├── constants/     # Application constants
│       │   ├── hooks/         # Custom React hooks
│       │   ├── lib/          # Utility libraries
│       │   ├── providers/    # Context providers
│       │   ├── trpc/         # tRPC configuration
│       │   ├── types/        # TypeScript type definitions
│       │   └── zod-schemas/  # Zod validation schemas
│       ├── public/           # Static assets
│       └── package.json      # App dependencies
│
├── packages/
│   ├── db/                   # Database package
│   │   ├── src/
│   │   │   ├── schema/      # Drizzle database schemas
│   │   │   └── index.ts     # Database exports
│   │   └── migrations/      # Database migration files
│   │
│   ├── utilities/           # Shared utilities
│   │   └── src/
│   │       └── env/        # Environment configuration
│   │
│   ├── eslint-config/      # Shared ESLint configuration
│   └── typescript-config/  # Shared TypeScript configuration
│
├── env-links.sh            # Environment symlink script
├── turbo.json             # Turbo configuration
├── package.json           # Root package configuration
└── yarn.lock             # Dependency lock file

Create a .env file in the root directory with the following variables:

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/invoicely"

# Authentication
BETTER_AUTH_SECRET="your-secret-key"
BETTER_AUTH_URL="http://localhost:3000"
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Cloudflare R2 Storage
CF_R2_ENDPOINT="your-r2-endpoint"
CF_R2_ACCESS_KEY_ID="your-access-key"
CF_R2_SECRET_ACCESS_KEY="your-secret-key"
CF_R2_BUCKET_NAME="your-bucket-name"
CF_R2_PUBLIC_DOMAIN="your-public-domain"

# Analytics
NEXT_PUBLIC_POSTHOG_HOST="your-posthog-host"
NEXT_PUBLIC_POSTHOG_KEY="your-posthog-key"

# Public URLs
NEXT_PUBLIC_BASE_URL="http://localhost:3000"
NEXT_PUBLIC_TRPC_BASE_URL="http://localhost:3000/api/trpc"

The project uses a symlink-based approach for environment management:

• Run yarn sys-link to create symlinks from the root .env file to all apps
• This ensures consistent environment variables across the monorepo
• Environment variables are validated using @t3-oss/env-nextjs and Zod

yarn dev              # Start development servers for all apps
yarn build            # Build all apps for production
yarn start            # Start production servers
yarn lint             # Lint all packages
yarn lint:fix         # Fix linting issues
yarn format           # Format code with Prettier
yarn check-types      # Type check all packages

# Database Operations
yarn db:generate      # Generate database schema
yarn db:migrate       # Run database migrations
yarn db:push          # Push schema changes to database
yarn db:studio        # Open Drizzle Studio

# Utility Scripts
yarn sys-link         # Create environment symlinks
yarn reset-repo       # Clean all build artifacts

yarn dev              # Start Next.js development server
yarn build            # Build for production
yarn start            # Start production server
yarn lint             # Lint the web app

• Directories: Use lowercase with dashes (e.g., components/auth-wizard)
• Components: Use PascalCase for component files (e.g., UserProfile.tsx)
• Client Components: Add .client.tsx suffix for components using "use client"
• Utilities: Use camelCase for utility files (e.g., formatCurrency.ts)

• Variables: Use camelCase (e.g., userName, isLoading, hasError)
• Constants: Use SCREAMING_SNAKE_CASE (e.g., R2_PUBLIC_URL, TOAST_OPTIONS)
• Functions: Use camelCase with descriptive verbs (e.g., createInvoice, validateEmail)
• Booleans: Prefix with auxiliary verbs (e.g., isLoading, hasPermission, canEdit)

• Interfaces: Use PascalCase (e.g., UserProfile, InvoiceData)
• Zod Schemas: Prefix with "Zod" (e.g., ZodInvoiceSchema, ZodUserSchema)
• Type Exports: Use named exports, avoid default exports

• Use the function keyword for pure functions
• Prefer named exports over default exports
• Use functional and declarative programming patterns
• Structure files: exported component, subcomponents, helpers, static content, types

We welcome contributions to Invoicely! Please follow these guidelines:

• Format: profilename/featurename
• Examples: john/add-dark-mode, sarah/fix-invoice-validation

• PR Title Format: type: description
  • feature: add invoice templates
  • fix: resolve authentication redirect issue
  • chore: update dependencies

1. Fork the repository
2. Create a feature branch following the naming convention
3. Make your changes following the code style guidelines
4. Test your changes thoroughly
5. Submit a pull request with a descriptive title and description

• Do NOT push database migrations - Migrations should be reviewed and managed by maintainers
• Ensure all tests pass before submitting
• Follow the existing code style and conventions
• Update documentation for any new features

• All PRs require review from at least one maintainer
• Ensure your code follows TypeScript best practices
• Write meaningful commit messages
• Keep PRs focused and atomic

• Next.js Documentation
• React Documentation
• TypeScript Documentation

• tRPC Documentation
• TanStack Query Documentation
• Jotai Documentation
• Zod Documentation

• Drizzle ORM Documentation
• Better Auth Documentation
• Neon Database Documentation

• Tailwind CSS Documentation
• Radix UI Documentation
• Shadcn/ui Documentation
• Lucide Icons

• Turbo Documentation
• ESLint Documentation
• Prettier Documentation

This project is licensed under the MIT License - see the LICENSE file for details.