npm package: @realtimex/realtimex-crm
Description: RealTimeX CRM - A full-featured CRM with zero cloud costs and complete privacy.
Author: RealTimeX Team
Latest version: 0.63.3

# RealTimeX CRM

A full-featured CRM with zero cloud costs and complete privacy. Fork of [Atomic CRM](https://github.com/marmelab/atomic-crm) with enhanced "Bring Your Own Database" configuration.

https://github.com/user-attachments/assets/0d7554b5-49ef-41c6-bcc9-a76214fc5c99

RealTimeX CRM is free and open-source.

## Live Demo

Experience RealTimeX CRM immediately: [realtimex-crm.vercel.app](https://realtimex-crm.vercel.app/)

**Admin Credentials:**
- **Email**: `janedoe@realtimex.ai`
- **Password**: `crmdemo`

> [!NOTE]
> This demo uses an in-memory database. All changes are local to your browser session and will reset upon refreshing the page.

## Features

- 📇 **Organize Contacts**: Keep all your contacts in one easily accessible place.
- ⏰ **Create Tasks & Set Reminders**: Never miss a follow-up or deadline.
- 📝 **Take Notes**: Capture important details and insights effortlessly.
- ✉️ **Capture Emails**: CC RealTimeX CRM to automatically save communications as notes.
- 📊 **Manage Deals**: Visualize and track your sales pipeline in a Kanban board.
- 🔄 **Import & Export Data**: Easily transfer contacts in and out of the system.
- 🔐 **Control Access**: Log in with Google, Azure, Keycloak, and Auth0.
- 📜 **Track Activity History**: View all interactions in aggregated activity logs.
- 🔗 **Integrate via API**: Connect seamlessly with other systems using our API.
- 🛠️ **Customize Everything**: Add custom fields, change the theme, and replace any component to fit your needs.
- 🗄️ **Bring Your Own Database**: Configure Supabase connection via UI or environment variables.

## Quick Start

### Option 1: Use the CLI (Recommended)

Create a new CRM project in seconds:

```bash
npx create-realtimex-crm@latest
```

The CLI will guide you through:
1. Choosing a template (standalone app, RealTimeX Local App, or component)
2. Configuring Supabase (optional)
3. Setting up your project structure

Then:
```bash
cd my-crm
npm install
npm run dev
```

### Option 2: Clone and Customize

To run this project locally, you will need:

- Node 22 LTS
- A free Supabase account (create at [supabase.com](https://supabase.com))

Clone the repository:

```sh
git clone https://github.com/therealtimex/realtimex-crm.git
cd realtimex-crm
```

Install dependencies:

```sh
npm install
```

Start the development server:

```sh
npm run dev
```

Access the app at [http://localhost:5173/](http://localhost:5173/)

**First Launch:**
1. Setup wizard appears automatically
2. Choose one of:
   - **Connect to Supabase**: Enter your project URL and API key
3. Configure via:
   - Setup wizard (recommended for users)
   - OR set environment variables in `.env.development.local`:
     ```env
     VITE_SUPABASE_URL=https://xxxxx.supabase.co
     VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
     ```

**Managing Your Remote Supabase:**
- Dashboard: https://supabase.com/dashboard/project/YOUR_PROJECT_ID
- Storage: View attachments in Supabase dashboard
- Database: Run migrations via Settings → Database in the app

## User Documentation

1. [User Management](./doc/src/content/docs/users/user-management.mdx)
2. [Importing And Exporting Data](./doc/src/content/docs/users/import-contacts.mdx)
3. [Inbound Email](./doc/src/content/docs/users/inbound-email.mdx)

## Deploying to Production

1. [Configuring Supabase](./doc/src/content/docs/developers/supabase-configuration.mdx)
2. [Configuring Inbound Email](./doc/src/content/docs/developers/inbound-email-configuration.mdx) *(optional)*
3. [Deployment](./doc/src/content/docs/developers/deploy.mdx)

## Customizing RealTimeX CRM

To customize RealTimeX CRM, you will need TypeScript and React programming skills as there is no graphical user interface for customization. Here are some resources to assist you in getting started.

1. [Customizing the CRM](./doc/src/content/docs/developers/customizing.mdx)
2. [Creating Migrations](./doc/src/content/docs/developers/migrations.mdx) *(optional)*
3. [Architecture Decisions](./doc/src/content/docs/developers/architecture-choices.mdx) *(optional)*

## Testing Changes

This project contains unit tests. Run them with the following command:

```sh
npm test
```

You can add your own unit tests powered by Vitest anywhere in the `src` directory. The test files should be named `*.test.tsx` or `*.test.ts`.

## Development Commands

```sh
npm install              # Install dependencies
npm run dev              # Start development server
npm test                 # Run unit tests (vitest)
npm run typecheck        # Run TypeScript type checking
npm run lint             # Run ESLint and Prettier checks
npm run build            # Build production bundle
npm run serve            # Serve production build locally

# Developer commands (remote Supabase management)
npx supabase db push     # Push migrations to remote Supabase
```

## Registry

RealTimeX CRM components are published as a Shadcn Registry file:
- The `registry.json` file is automatically generated by the `scripts/generate-registry.mjs` script as a pre-commit hook.
- The registry is automatically published by the CI/CD pipeline

> [!WARNING]
> If the `registry.json` misses some changes you made, you MUST update the `scripts/generate-registry.mjs` to include those changes.

## CLI Templates

The `create-realtimex-crm` CLI provides three templates:

### 1. Standalone App
A complete CRM application ready to deploy:
- Full Vite + React setup
- TypeScript configuration
- Production build scripts
- Environment-based configuration

### 2. RealTimeX Local App
CRM integrated with RealTimeX.ai platform:
- `@realtimex/app-sdk` integration
- Auto-scoped data by user
- Parent-child user support
- Platform authentication
- See `LOCAL_APP.md` in generated project for details

### 3. Component Integration
Use RealTimeX CRM as a component in your existing app:
- Install via npm
- Import and configure
- Example integration code included

## NPM Package

RealTimeX CRM is available as an npm package:

```bash
npm install realtimex-crm
```

The package includes all source code, components, and Supabase migrations for easy integration.

## License

This project is licensed under the MIT License. Original project courtesy of [RealTimeX](https://realtimex.ai). See the [LICENSE.md](./LICENSE.md) file for details.

## Credits

This project is a fork of [Atomic CRM](https://github.com/marmelab/atomic-crm) by Marmelab, enhanced with:
- "Bring Your Own Database" UI configuration
- Simplified deployment workflows
- NPM package distribution
- RealTimeX App SDK integration support (planned)