Running in Development
Relevant source files
The following files were used as context for generating this wiki page:This guide provides instructions for setting up and running the MessageJS project in a local development environment. It covers the necessary prerequisites, project structure, and the commands required to start the backend services and frontend packages. The project is a monorepo containing the core API, a client SDK, and a dashboard application.
The development environment relies on Node.js, npm workspaces for managing the monorepo packages, and Docker for running the required database service. Following these steps will allow a developer to run the entire stack locally for testing and feature development.
1. Prerequisites
Before starting, ensure you have the following installed on your system:
- Node.js: Version
20.0.0or higher. - npm: Version
10.0.0or higher. - Docker and Docker Compose: To run the PostgreSQL database.
Sources: package.json:23-26, docker-compose.yml:6-9
2. Initial Setup
First, clone the repository and install all dependencies using npm install. The project uses npm workspaces, so this command will install dependencies for all packages in the packages/* directory.
# Clone the repository
git clone https://github.com/messagejs/messagejs.git
cd messagejs
# Install dependencies for all workspaces
npm install
After installation, you can build all packages to ensure everything is correctly configured.
# Build all packages
npm run build
Sources: README.md:31-37, package.json:8-10
3. Project Structure
MessageJS is a monorepo, with individual packages located in the packages/ directory. Understanding this structure is key to running the project.
The diagram below illustrates the high-level structure of the monorepo.
This diagram shows the monorepo root and its primary packages.
Sources: mono-repo.md, package.json:7, README.md:21-26
4. Running Backend Services
The core functionality of MessageJS requires a backend API and a database.
4.1. Start the PostgreSQL Database
The project uses Docker Compose to manage the PostgreSQL database for development.
-
Navigate to the root of the project.
-
Run the following command to start the database service in the background:
docker-compose up -d
This command will create a PostgreSQL container named messagejs_postgres_dev. The database will be accessible on localhost:5432.
The following diagram shows the Docker service configuration.
This diagram shows the process of starting the PostgreSQL container via Docker Compose.
Sources: docker-compose.yml
Database Configuration
The docker-compose.yml file defines the configuration for the postgres service.
| 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. |
POSTGRES_USER | messagejs | The username for the database. |
POSTGRES_PASSWORD | password | The password for the database user. |
POSTGRES_DB | messagejs_dev | The name of the development database. |
ports | "5432:5432" | Maps the container's port 5432 to the host's port 5432. |
volumes | postgres_data | Named volume for data persistence. |
restart | always | Ensures the container restarts if it stops. |
Sources: docker-compose.yml:15-36
4.2. Start the Core API
The backend is an Express.js server located in the @messagejs/core package. You can start it in development mode with hot-reloading using a root-level npm script.
# Start core backend (runs on port 3001)
npm run core
This command executes npm run dev --workspace=packages/core, which in turn runs tsx watch src/index.ts. The API server will start and listen on http://localhost:3001.
Sources: package.json:16, packages/core/package.json:10, packages/core/src/index.ts:15
5. Running Frontend and Client Packages
The monorepo contains several other packages that can be run for development.
Development Scripts
The root package.json provides convenient scripts to run individual packages from the project root.
| Script | Command | Description |
|---|---|---|
npm run core | npm run dev --workspace=packages/core | Starts the backend API in watch mode. |
npm run client | npm run dev --workspace=packages/client | Builds and watches the client SDK for changes. |
npm run dashboard | npm run dev --workspace=packages/dashboard | Starts the Next.js dashboard development server. |
Sources: package.json:16-18
Development Environment Overview
The following diagram illustrates the complete local development setup, with the developer running commands that start the various services which communicate with each other.
This diagram shows the relationship between the developer, the npm scripts, and the running services in the local environment.
Sources: package.json:16-18, docker-compose.yml, packages/core/src/index.ts:15, packages/dashboard/package.json:8
6. Summary
To run MessageJS in a development environment, a developer must first install the prerequisites (Node.js, Docker), clone the repository, and install dependencies. The backend services are started by running docker-compose up -d for the database and npm run core for the API server. Other packages like the dashboard can be started with their respective npm run <package-name> commands from the project root. This setup provides a complete, isolated environment for building and testing MessageJS.
Sources: README.md:31-45, docker-compose.yml