marmelab/atomic-crm: Self-Hosted CRM with React, Supabase

marmelab/atomic-crm: Self-Hosted CRM with React^{↗ Bright Coding Blog}, Supabase, and Full Customization

Developers building internal tools for sales teams often face a familiar dilemma: adopt a bloated SaaS CRM with per-seat pricing and limited API access, or invest months building something custom from scratch. Neither option sits well with teams that need control over data residency, deep integrations with existing infrastructure, or UI patterns that match their design system. marmelab/atomic-crm addresses this gap directly—an open-source, self-hosted CRM built with modern web primitives that you can deploy, extend, and own entirely.

This article breaks down what marmelab/atomic-crm offers, how it fits into the current landscape of developer-oriented CRMs, and what it takes to get running locally or in production. The focus keyword marmelab/atomic-crm appears throughout as we examine its architecture, documented capabilities, and practical trade-offs.

What is marmelab/atomic-crm?

marmelab/atomic-crm is a full-featured customer relationship management system maintained by Marmelab, a French software consultancy known for open-source developer tools including react-admin. The project lives at https://github.com/marmelab/atomic-crm and carries an MIT License. As of the latest commit (2026-07-13), it has accumulated 1,144 GitHub stars and 728 forks, with TypeScript as its primary language.

The stack is deliberately modern and opinionated: React for the frontend, shadcn/ui components (via the shadcn-admin-kit variant), and Supabase for the backend—encompassing Postgres, authentication, real-time subscriptions, and object storage. This combination matters because it reflects where frontend development^{↗ Bright Coding Blog} has converged: component libraries that ship copy-pasteable code rather than opaque npm dependencies, and backend-as-a-service platforms that eliminate the need to maintain separate API servers for standard CRUD operations.

The "atomic" naming signals a design philosophy: components are composable, replaceable, and published through a shadcn registry for incremental updates. This is not a monolithic application you configure through a web UI alone; it is source code you own, modify, and redeploy. For teams already invested in React and TypeScript, this represents a meaningful alternative to both proprietary CRMs and headless CMS platforms that require rebuilding CRM-specific logic from scratch.

Key Features

The README documents ten specific capabilities, each grounded in concrete functionality rather than aspirational marketing:

Contact Organization provides a centralized repository for all contact records—foundational for any CRM, but implemented here with the extensibility to add custom fields as business requirements evolve.

Tasks and Reminders support deadline-driven workflows, with the system surfacing follow-ups before they slip. This integrates with the activity history to create accountability trails.

Notes capture unstructured context—meeting outcomes, research, relationship details—without forcing everything into rigid schema fields.

Email Capture through CC functionality automatically ingests communications as notes. This reduces manual data entry, a consistent friction point in CRM adoption.

Deal Management uses a Kanban board for pipeline visualization. The tweet highlighting "Kanban deal tracking" directly reflects this capability, which sales teams expect as table stakes but which many open-source CRMs implement poorly or omit entirely.

Import/Export enables data portability—critical for migration scenarios and for avoiding vendor lock-in, even with open-source software.

Authentication supports Google, Azure, Keycloak, and Auth0 out of the box. This breadth matters for enterprise contexts where identity provider consolidation is non-negotiable.

Activity History aggregates all interactions into unified logs, preventing the fragmented context that occurs when email, calls, and notes live in separate silos.

API Integration exposes a REST interface for connecting to external systems—essential for the CRM to participate in broader automation workflows.

Customization extends to custom fields, theming, and component replacement. The shadcn registry mechanism means updates can be pulled incrementally without full rewrites.

Use Cases

Seed-Stage Startup Replacing Spreadsheets Early-stage companies often outrun Notion or Airtable for sales tracking. marmelab/atomic-crm provides a migration path: import existing contact data, configure deal stages to match their sales motion, and self-host to avoid per-seat costs that compound as the team grows. The Kanban view gives founders visibility without the overhead of Salesforce implementation.

Agency Managing Multiple Client Pipelines Digital agencies running sales for themselves and white-label solutions benefit from source-code ownership. They can fork marmelab/atomic-crm per client, customize branding through theming, and maintain data isolation through separate Supabase instances—without licensing negotiations for each deployment.

Enterprise Team Requiring SSO Compliance Organizations with Azure AD or Keycloak mandates can deploy marmelab/atomic-crm behind existing identity infrastructure. The documented auth integrations reduce the integration work that typically blocks internal tool adoption, while self-hosting satisfies data residency requirements that SaaS CRMs struggle with.

Developer Tooling Company Building Community Open-source projects with commercial offerings need lightweight CRM for contributor and prospect tracking. The email capture feature automatically archives outreach, while the API enables integration with existing newsletter and analytics stacks. The MIT License eliminates legal review friction.

Consulting Firm Extending for Vertical Specialization Firms serving specific industries (legal, real estate, healthcare) can fork and extend with domain-specific custom fields and validation logic. The component architecture means UI changes don't require fighting a proprietary extension framework.

Installation & Setup

The README specifies exact prerequisites and commands. Reproduce them precisely:

Prerequisites:

• Make
• Node 22 LTS
• Docker^{↗ Bright Coding Blog} (required by Supabase)

Step 1: Fork and clone

# Fork the repository to your GitHub account first, then:
git clone https://github.com/[username]/atomic-crm.git

This creates your own copy for modification and deployment. The fork model matters because you'll likely customize components and configuration.

Step 2: Install dependencies

cd atomic-crm
make install

The make install target handles both frontend and backend dependencies, including provisioning a local Supabase instance through Docker. This is not a lightweight npm install—it pulls container images for Postgres, the Supabase API gateway, and associated services.

Step 3: Start the application

make start

This concurrently launches:

• Vite dev server (frontend, typically port 5173)
• Local Supabase instance (API and database)
• Postgres via Docker

Access the application at http://localhost:5173/. First launch prompts for initial user creation.

Debug endpoints available:

• Supabase dashboard: http://localhost:54323/
• REST API: http://127.0.0.1:54321
• Attachments storage: http://localhost:54323/project/default/storage/buckets/attachments
• Inbucket email testing: http://localhost:54324/

The Inbucket service is particularly useful for verifying email capture functionality without sending to real inboxes during development.

Real Code Examples

The README contains limited explicit code snippets, which reflects the project's orientation toward command-line workflows and component composition rather than API-heavy configuration. We present what is documented, with explicit framing.

Registry Update Command

npx shadcn add https://marmelab.com/atomic-crm/r/atomic-crm.json -o

This command pulls the latest published components from Marmelab's shadcn registry. The -o flag (overwrite) ensures local modifications are replaced with upstream versions. This is the primary mechanism for receiving updates without manual patch application or git merge conflicts. The registry file is auto-generated by scripts/generate-registry.mjs as a pre-commit hook, and published through CI/CD to the marmelab.com/atomic-crm/r/atomic-crm.json endpoint.

Unit Test Execution

make test

Runs Jest-powered tests anywhere in the src directory matching *.test.tsx or *.test.ts patterns. The Makefile abstraction hides whether this invokes jest directly, npm test, or pnpm test—the point is consistent command interface regardless of package manager details.

End-to-End Test Execution (Development Mode)

make test-e2e

This launches Playwright in UI mode against a Vite server with hot reload. The README explicitly notes this differs from CI behavior: make test-e2e optimizes for development velocity, while CI runs against built assets.

End-to-End Test Execution (CI-Equivalent)

make start-e2e-ci
# In separate terminal:
npx playwright test --ui

First command serves the production build; second runs Playwright against it. This two-step pattern matters when debugging discrepancies between development and CI environments—common with Vite's different handling of environment variables and module resolution between vite dev and vite build.

The README does not contain application-level code examples (React component usage, Supabase client configuration, or API call patterns). Developers should expect to read source files directly or consult the documentation site for implementation guidance.

Advanced Usage & Best Practices

Based on the documented architecture, several practices emerge for production deployments:

Registry Hygiene: The pre-commit hook generating registry.json can miss manual file additions. The README includes an explicit warning: if your changes don't appear in the registry, modify scripts/generate-registry.mjs rather than editing registry.json directly. Treat this as infrastructure code requiring the same review rigor as application logic.

Environment Parity: The development (make test-e2e) and CI (make start-e2e-ci) test paths diverge intentionally. For critical path testing, run both locally before pushing—Vite's dev server and production build can behave differently regarding tree-shaking, environment variable injection, and dynamic import handling.

Authentication Provider Selection: With four supported providers (Google, Azure, Keycloak, Auth0), evaluate based on your existing infrastructure rather than defaulting to Google. Keycloak and Azure integrations suggest enterprise orientation; implementing multiple providers during development validates the abstraction layer even if production uses only one.

Data Migration Strategy: The import/export feature supports initial migration, but plan for ongoing synchronization if replacing an active system. The Postgres foundation means standard tools (pg_dump, logical replication) supplement application-level import/export for large datasets.

For teams evaluating [INTERNAL_LINK: self-hosted open-source alternatives to SaaS CRMs], marmelab/atomic-crm's combination of modern React patterns and Supabase backend represents a specific architectural bet worth understanding.

Comparison with Alternatives

ERPNext CRM offers broader enterprise resource planning integration but carries heavier operational overhead. SuiteCRM provides mature feature depth but requires PHP specialization increasingly rare in modern frontend teams. marmelab/atomic-crm's position is specific: teams that want CRM functionality without leaving their React/TypeScript toolchain, and that value component-level customization over out-of-the-box breadth.

FAQ

What Node version is required? Node 22 LTS, per the README. Earlier versions may work but are untested.

Is Docker mandatory? Yes—for the Supabase backend. The frontend alone can run without it, but core functionality requires the full stack^{↗ Bright Coding Blog}.

Can I use a cloud Supabase instance instead of local Docker? The README documents local setup only. Cloud Supabase would require manual configuration of environment variables for the API URL and anon key.

What authentication providers work besides Google? Azure, Keycloak, and Auth0 are documented alternatives.

How do I update to the latest version? Use the shadcn registry command: npx shadcn add https://marmelab.com/atomic-crm/r/atomic-crm.json -o

Is commercial support available? The README does not mention commercial support. Marmelab is a consultancy; direct engagement would be through standard business channels.

What testing frameworks are used? Jest for unit tests, Playwright for end-to-end tests.

Conclusion

marmelab/atomic-crm occupies a precise niche: it is not the most feature-complete open-source CRM, nor the simplest to deploy, but it offers something increasingly valuable to technical teams—complete source ownership in a stack they already understand. The 1,144 stars and 728 forks suggest growing traction, though it remains younger and less proven than decade-old alternatives.

This tool fits teams where at least one developer can maintain a React/TypeScript codebase, where self-hosting is a requirement rather than inconvenience, and where the Kanban pipeline view and email capture integration match actual workflow needs. It is less suitable for non-technical teams seeking one-click SaaS deployment or organizations deeply invested in PHP or Python server stacks.

The MIT License removes legal barriers to experimentation. Fork the repository at https://github.com/marmelab/atomic-crm, run through the local setup, and evaluate whether the component architecture matches your customization requirements before committing to production deployment.