Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:This guide provides comprehensive instructions for setting up the MessageJS development environment. MessageJS is a monorepo project designed to provide a unified API for sending messages through various chat platforms like WhatsApp, Telegram, and SMS. The system consists of a Node.js backend (@messagejs/core), a client-side SDK (@messagejs/client), and a dashboard, all managed within a single repository.
The setup process involves cloning the repository, installing dependencies, configuring and running a PostgreSQL database using Docker, and starting the backend and client development servers. Following these steps will result in a fully functional local instance of the MessageJS API, ready for development and testing.
Sources: README.md:1-12, package.json:2-8
1. Prerequisites
Before beginning the installation, ensure your development machine has the following software installed:
- Node.js: Version
20.0.0or higher. - npm: Version
10.0.0or higher. - Docker and Docker Compose: Required for running the PostgreSQL database.
Sources: package.json:23-26, docker-compose.yml:6-9
2. Repository and Dependency Installation
First, clone the repository from GitHub and install the necessary dependencies for all packages in the monorepo.
# Clone the repository
git clone https://github.com/messagejs/messagejs.git
cd messagejs
# Install dependencies for all workspaces
npm install
The npm install command will install dependencies for all packages defined in the workspaces array of the root package.json, including @messagejs/core, @messagejs/client, and @messagejs/dashboard.
Sources: README.md:29-35, package.json:6-8
3. Database Setup
MessageJS uses a PostgreSQL database for data persistence. The development environment is configured to use Docker to create a consistent and isolated database instance.
Running the Database Container
To start the database, run the following command from the root of the project:
docker-compose up -d
This command reads the docker-compose.yml file and starts a PostgreSQL 15 container in the background. The database will be accessible on localhost:5432.
Sources: docker-compose.yml:8-11
Database Configuration
The docker-compose.yml file defines the postgres service with the following configuration:
| Parameter | Value | Description |
|---|---|---|
image | postgres:15-alpine | The Docker image used for the database. |
container_name | messagejs_postgres_dev | The name of the running container. |
ports | - "5432:5432" | Maps the container's port 5432 to the host's port 5432. |
restart | always | Ensures the container restarts automatically if it stops. |
volumes | - postgres_data:/var/lib/postgresql/data | Persists database data on the host machine. |
The following environment variables are used to configure the database instance. These must match the DATABASE_URL in the .env file for the @messagejs/core package.
| Variable | Value |
|---|---|
POSTGRES_USER | messagejs |
POSTGRES_PASSWORD | password |
POSTGRES_DB | messagejs_dev |
Sources: docker-compose.yml:13-36
The diagram below illustrates how the local development environment components interact.
This diagram shows the developer starting the Core API and the Docker container, which allows the API to connect to the PostgreSQL database.
Sources: docker-compose.yml, packages/core/src/index.ts:18-19
4. Backend Setup (@messagejs/core)
The backend is an Express.js application that serves the main API.
Running the Core API
To start the backend development server, run the following command from the project root:
npm run core
This script executes tsx watch src/index.ts within the @messagejs/core package, starting a server with hot-reloading. The API will be available at http://localhost:3001.
Sources: package.json:14, packages/core/package.json:10
The server entry point (packages/core/src/index.ts) initializes an Express app, applies express.json() middleware, and sets up a health check route at /. The main application routes are mounted under /api/v1/messages.
Sources: packages/core/src/index.ts:15-37
Database Schema
The backend uses Prisma as its ORM. The database schema is defined in packages/core/prisma/schema.prisma and includes models for User, Project, Service, Template, and MessageLog.
The following Entity-Relationship diagram visualizes the database structure.
This diagram shows the relationships between the core data models, such as a User having multiple Projects, and a Project containing Services, Templates, and MessageLogs.
Sources: packages/core/prisma/schema.prisma:29-100
5. Monorepo Structure and Scripts
The project is organized as a monorepo, with distinct packages located in the packages/ directory.
Package Overview
This diagram shows the high-level structure of the monorepo.
Sources: mono-repo.md
Key Development Scripts
The root package.json contains scripts to manage all workspaces simultaneously.
| Script | Command | Description |
|---|---|---|
build | npm run build --workspaces | Builds all packages in the monorepo. |
dev | npm run dev --workspaces | Runs all packages in development mode. |
core | npm run dev --workspace=packages/core | Starts the core backend development server. |
client | npm run dev --workspace=packages/client | Builds and watches the client SDK. |
dashboard | npm run dev --workspace=packages/dashboard | Starts the dashboard development server. |
typecheck | npm run typecheck --workspaces | Runs TypeScript type checking across all packages. |
Sources: package.json:9-16
By following these steps, a developer can successfully set up a local MessageJS environment. This includes a running database, a functional backend API, and the tools needed to develop the client SDK and other related packages.