Skip to content
narrowstacksPublic

About

Dorkroom is a collection of specialized calculators and tools designed for analog photographers and darkroom enthusiasts. Built to keep complex exposure math, border calculations, and chemistry planning out of your way so you can focus on making beautiful prints.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

9 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,151 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Dorkroom.art

Skip the math. Make prints!

Dorkroom Homepage

Dorkroom.art is a collection of specialized calculators and tools designed for analog photographers and darkroom enthusiasts. Built to keep complex exposure math, border calculations, and chemistry planning out of your way so you can focus on making beautiful prints.

Version License

React 19 TypeScript Tailwind CSS TanStack Query Biome

Uptime Robot status GitHub Actions Workflow Status GitHub Issues or Pull Requests GitHub Issues or Pull Requests

What is Dorkroom?

Dorkroom provides useful calculators for darkroom printing, film development, and photography.

Film Development Resources

  • Development Recipes - Film + chemistry pairings and development times with many manufacturer approved development recipes, including a volume mixer.
  • Film Database - List of films and their information provided by the API.

Printing Tools

  • Border Calculator - Calculate precise print borders to maintain your desired aspect ratio with the border sizes you want.
  • Resize Calculator - Scale prints to be larger or smaller without endless test strips (some test strips still necessary!)
  • Stops Calculator - Translate exposure stops into seconds.
  • Mat Cut Calculator - Plan single-window mats with independent borders; get exact window openings and mat-cutter guide-bar settings.

Shooting Tools

  • Reciprocity Calculator - Calculate exposure time correction for long exposure (reciprocity) failure on films.
  • Exposure Calculator - Balance aperture, shutter speed, and ISO; calculate equivalent exposures across settings.
  • Lens Equivalency Calculator - Compare equivalent focal lengths and field of view across APS-C, Full Frame, and Medium Format.

Documentation

  • Dorkroom Docs - How-to guides and reference material for every tool. It lives in its own repository and is stitched in through Vercel Microfrontends.

iOS App

A native iOS app (Expo / React Native, targeting iOS 26 with Liquid Glass styling) is in development under apps/mobile/. It reuses the same @dorkroom/logic and @dorkroom/api packages as the web app, so the math is identical on both platforms.

Working today:

  • Border, Mat Cut, Reciprocity, and Resize calculators
  • Lens Equivalency, converting focal lengths between sensor and film formats
  • Camera Exposure, EV from aperture, shutter speed, and ISO, with lighting presets, equivalent exposures, and an A/B comparison
  • Exposure, the f-stop and time calculator the web app calls Stops
  • Light Meter, metering through the camera, with aperture- and shutter-priority solving
  • Development Recipes browsing, with a multi-stage process timer and editable timer presets
  • Film Log for rolls, shots, and gear, using the live film database as its film picker

The app versions independently of the web app. See apps/mobile/CHANGELOG.md.

In the Works

  • iOS parity - The film database is not yet browsable on iOS.
  • Kindle browser support - Support for the app on the strange Kindle browser.
    • Help needed! The site currently does not render on Kindle browsers ☹️

Development Quick Start

Prerequisites

  • Node.js 24.x (required)
  • Bun (required - uses Bun workspaces)

Install Bun:

# macOS/Linux
curl -fsSL https://bun.sh/install | bash
# Windows (via PowerShell)
powershell -c "irm bun.sh/install.ps1|iex"

Development

# Clone the repository
git clone https://github.com/narrowstacks/dorkroom.git
cd dorkroom

# Install dependencies (requires Bun)
bun install

# Optional — only needed to work on the api/ serverless endpoints.
# The web calculators run fully client-side with no env vars.
cp .env.example .env
# Edit .env with your Supabase credentials

# Build all packages
bun run build

# Start development server
bun run dev

# Open the URL Vite prints (the @vercel/microfrontends plugin picks the port)

Building

# Build for production
bun run build

# Build specific package
turbo run build --filter=@dorkroom/logic

Testing

# Run linting, testing, building, and typechecking in one go
bun run test

# Run test for only one package (logic, ui, api)
turbo run test --filter=@dorkroom/logic

Technology Stack

  • Frontend: React 19 with TypeScript (typecheck runs on bun check, Bun's built-in TypeScript 7 checker; build runs on stable TypeScript 7 via the typescript-7 alias; typescript stays on 6.x to supply the compiler API that TypeScript 7.0 doesn't ship)
  • Styling: Tailwind CSS 4.3 with custom darkroom theme
  • Build Tool: Vite 8 (Rolldown/Oxc) with Turborepo
  • Testing: Vitest 4 with Testing Library (happy-dom environment)
  • Linting: oxlint (Rust) · Formatting: bun fmt (Prettier-compatible: single quotes, semicolons, trailing commas)
  • State Management: TanStack Query v5 for server state
  • Routing: TanStack Router v1 with file-based routing
  • Forms: TanStack Form v1 with Zod validation
  • Tables: TanStack Table v8 for data tables
  • Virtualization: TanStack Virtual v3 for performant list rendering
  • Schema Validation: Zod 4
  • Monorepo: Turborepo with Bun workspaces

Architecture

Dorkroom is built as a Turborepo monorepo with clear separation of concerns:

apps/
  dorkroom/           # Main React (web) application with TanStack Router file-based routing
    src/routes/       # File-based route definitions
  mobile/             # Native iOS app (Expo / React Native), reuses @dorkroom/logic + @dorkroom/api
packages/
  ui/                 # Shared UI components (@dorkroom/ui)
  logic/              # Business logic, hooks, queries (@dorkroom/logic)
  api/                # API utilities and TypeScript client (@dorkroom/api)
api/                  # Serverless API endpoints (Vercel functions)

Key Architectural Patterns

  • File-Based Routing: TanStack Router with automatic route tree generation
  • Type-Safe State: TanStack Query for server state with query key structure
  • Form Validation: TanStack Form with Zod schemas for runtime validation
  • Data Tables: TanStack Table for sorting, filtering, and pagination

Features

  • Responsive Design - Works on desktop, tablet, and mobile
  • Multiple Themes - Standard dark and light themes, as well as with black and white high contrast (ideal for e-ink) and black and red darkroom theme
    • Darkroom theme: User beware! This will still likely fog paper if your screen is left near it long enough, especially with non-OLED screens. A warning about this will be added to the app soon.
  • Fast Calculations - Instant results with real-time validation
  • Type-Safe - Full TypeScript coverage with strict mode
  • Session Caching - Smart client-side caching with TanStack Query
  • File-Based Routing - Type-safe navigation with TanStack Router
  • Form Validation - Runtime schema validation with Zod
  • Virtualized Lists - Efficient rendering of large data sets with TanStack Virtual
  • Development Database - Tons of film development recipes
  • Open Source - Community-driven development under AGPL-3.0

API

Dorkroom provides a comprehensive API for accessing film development data, available both as a TypeScript client package and as REST endpoints for external integrations.

For detailed API documentation, see API.md

Quick Overview

  • TypeScript Client: @dorkroom/api package with search and caching
  • REST Endpoints: /api/films, /api/developers, /api/combinations
  • Features: Query parameters, partial-match search, request validation, CORS support
  • API Key Access: Contact aaron+dorkroom@affords.art to request a key for https://api.dorkroom.art
  • Authentication: X-API-Key header (request a key by email — see above)
  • Anonymous Namespace Bootstrap: bun run keys:anon-bootstrap (uses UNKEY_ROOT_KEY; requires ratelimit.*.limit and ratelimit.*.create_namespace on that key)

Contributing

We welcome contributions from the analog photography community! Please read our Code of Conduct before participating.

If your change adds or alters an analytics event, update PRIVACY.md and the /privacy page in the same PR. The rule is in PRIVACY.md.

Development Workflow

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/new-calculator

  3. Make your changes following our code organization guidelines:

    • Routes: Add new routes to apps/dorkroom/src/routes/ using file-based routing
    • Business Logic: Add calculations, utilities, types, and hooks to packages/logic/
    • UI Components: Add reusable components and contexts to packages/ui/
    • API Client: Add API utilities to packages/api/
    • Validation Schemas: Define Zod schemas in appropriate package
  4. Test your changes thoroughly:

    # Test specific packages
    turbo run test --filter=@dorkroom/logic
    turbo run test --filter=@dorkroom/ui
    turbo run test --filter=@dorkroom/dorkroom
  5. Run quality checks on affected packages:

    # Lint specific packages (oxlint + bun fmt check)
    turbo run lint --filter=@dorkroom/logic
    turbo run lint --filter=@dorkroom/ui
    turbo run lint --filter=@dorkroom/dorkroom
    
    # Type check specific packages
    turbo run typecheck --filter=@dorkroom/logic
    turbo run typecheck --filter=@dorkroom/ui
    turbo run typecheck --filter=@dorkroom/dorkroom
    
    # Format code with bun fmt
    bun run format
  6. Submit a pull request

Code Quality

This project maintains high code quality standards with package-specific tooling and modern development practices.

Package Organization

  • packages/logic/ - Pure TypeScript business logic (calculations, utilities, types, hooks, TanStack Query queries)
  • packages/ui/ - Reusable React components, contexts, and form components
  • packages/api/ - API utilities, TypeScript client, and data fetching functions
  • apps/dorkroom/ - Main application with file-based routes and app-specific components

Key Development Patterns

TanStack Ecosystem:

  • All data fetching uses TanStack Query v5 with proper query key structure
  • File-based routing with TanStack Router v1 for type-safe navigation
  • Form handling with TanStack Form v1 and Zod schema validation
  • Data tables with TanStack Table v8 for sorting, filtering, pagination
  • Virtualized lists with TanStack Virtual v3 for performant rendering of large datasets

Type Safety:

  • Strict TypeScript mode enabled
  • Zod schemas for runtime validation
  • Type-safe route parameters and search params
  • No any types (use unknown when type cannot be determined)

Quality Tools by Package

# Run quality checks on specific packages
turbo run test --filter=@dorkroom/logic        # Test business logic
turbo run test --filter=@dorkroom/ui           # Test UI components
turbo run test --filter=@dorkroom/dorkroom     # Test main application

turbo run lint --filter=@dorkroom/logic        # Lint business logic (oxlint)
turbo run lint --filter=@dorkroom/ui           # Lint UI components (oxlint)
turbo run lint --filter=@dorkroom/dorkroom     # Lint main application (oxlint)

turbo run typecheck --filter=@dorkroom/logic   # Type check business logic
turbo run typecheck --filter=@dorkroom/ui      # Type check UI components
turbo run typecheck --filter=@dorkroom/dorkroom # Type check main application

# Run across all projects
bun run test

# Format code with bun fmt (single quotes, semicolons, trailing commas)
bun run format

# Lint --fix (oxlint) and format (bun fmt)
bun run lint:fix

Project Commands

Command Description
bun run dev Start development server
bun run build Build all packages
bun run test Run lint, test, build, typecheck
bun run keys:anon-bootstrap Bootstrap/check anonymous Unkey namespace
turbo run test --filter=@dorkroom/logic Test specific package
bun run lint Run oxlint + bun fmt check
bun run format Format code with bun fmt
bun run lint:fix oxlint --fix + bun fmt

Changelog

See CHANGELOG.md for the web app's history of changes. The iOS app is tracked separately in apps/mobile/CHANGELOG.md.

Security

Found a security vulnerability? Please report it responsibly. See our Security Policy for details on how to report issues and what to expect.

License

AGPL 3.0 License - see the LICENSE file for the license text and NOTICE for how we read it.

The iOS app ships under one additional permission granted by AGPLv3 section 7, so that it can be distributed through app stores whose terms of service would otherwise conflict with the license. See LICENSE-EXCEPTION. It waives nothing about copyleft or source availability.

One package is MIT, not AGPL: @dorkroom/api, the TypeScript client for the public REST API. It is a standalone client with no AGPL dependencies, and copyleft on a client library would make it useless to the people it exists for. Import it into anything you like.

You are allowed to reproduce any film-development data on Dorkroom.art in any form, or post it on the Internet or any other computer network.

Support

If you find Dorkroom useful for your darkroom work:

  • ⭐ Star the project on GitHub
  • 🐛 Report bugs and suggest features
  • 🔗 Share with fellow analog photographers
  • $ Support the developers on Ko-fi or sponsor us on GitHub

Special Thanks

  • Harvey Milk Photo Center and its members, for being a great community, resource, and my source of inspiration and my gainful employment.
  • FilmDev.org, for providing a great database, and a great API allowing our users to import from said database.
  • DigitalTruth Massive Development Chart, for being a long time provider of film development time data, and whose interface frustrated me enough to make a whole alternative 😚.
    • And a really special thanks for disallowing republishing of your data "in any form or post on the Internet or any other computer network.", despite most of the data not being made by you! A real good motivator for adding the "official" development time tags to the development recipe page and sourcing directly from manufacturers.

About

Dorkroom is a collection of specialized calculators and tools designed for analog photographers and darkroom enthusiasts. Built to keep complex exposure math, border calculations, and chemistry planning out of your way so you can focus on making beautiful prints.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

9 stars

Watchers

0 watching

Forks

Sponsor this project

Used by

Contributors

Languages

Generated from nrwl/react-monorepo