Skip to main content

Run Novu locally

⚡ Immediate working space with Gitpod

Open in Gitpod

Requirements

  • Node.js version v16.15.1
  • MongoDB
  • Redis
  • (Optional) pnpm - Needed if you want to install new packages
  • (Optional) localstack (required only in S3 related modules)

Need help installing the requirements? Read more here.

Setup the project

After installing the required services on your machine, you can clone and setup your forked version of the project:

  • Fork Novu's repository. Clone or download your fork to your local machine.
  • Run the initial setup command npm run setup:project to install and build all dependencies.
  • Run the project locally using npm run start.

The npm run start will start all of the services in parallel including the APIs and web clients. If you only want to run parts of the platform, you can use the following run commands from the root project:

  • start:dev - Synonym to npm run start
  • start:web - Only starts the web management platform
  • start:ws - Only starts the WebSocket service for notification center updates
  • start:widget - Starts the widget wrapper project that hosts the notification center inside an iframe
  • start:api - Runs the API in watch mode
  • start:dal - Runs the Data Access Layer package in watch mode
  • start:shared - Starts the watch mode for the shared client and API library
  • start:node - Runs the @novu/node package in watch mode
  • start:notification-center - Runs and builds the React package for the Novu notification center

Set up your environment variables

The command npm run setup:project creates default environment variables that are required to run Novu in a development environment. However, if you want to test certain parts of Novu or run it in production mode, you need to change some of them. These are all the available environment variables:

API Backend
  • NODE_ENV (default: local)
    The environment of the app. Possible values are: dev, test, prod, ci, local
  • S3_LOCAL_STACK
    The AWS endpoint for the S3 Bucket required for storing various media
  • S3_BUCKET_NAME
    The name of the S3 Bucket
  • S3_REGION
    The AWS region of the S3 Bucket
  • PORT
    The port on which the API backend should listen on
  • FRONT_BASE_URL
    The base url on which your frontend is accessible for the user. (e.g. web.novu.co)
  • DISABLE_USER_REGISTRATION (default: false)
    If users should not be able to create new accounts. Possible values are: true, false
  • REDIS_HOST
    The domain / IP of your redis instance
  • REDIS_PORT
    The port of your redis instance
  • REDIS_PASSWORD
    Optional password of your redis instance
  • JWT_SECRET
    The secret keybase which is used to encrypt / verify the tokens issued for authentication
  • SENDGRID_API_KEY
    The api key of the Sendgrid account used to send various emails
  • MONGO_URL
    The URL of your MongoDB instance
  • NOVU_API_KEY
    The api key of web.novu.co used to send various emails
  • SENTRY_DSN
    The DSN of sentry.io used to report errors happening in production
WebSocket Service
  • NODE_ENV (default: local)
    The environment of the app. Possible values are: dev, test, prod, ci, local
  • SENTRY_DSN
    The DSN of sentry.io used to report errors happening in production
  • REDIS_HOST
    The domain / IP of your redis instance
  • REDIS_PORT
    The port of your redis instance
  • REDIS_DB_INDEX
    The database index of your redis instance
  • REDIS_PASSWORD
    Optional password of your redis instance
  • JWT_SECRET
    The secret keybase which is used to encrypt / verify the tokens issued for authentication
  • MONGO_URL
    The URL of your MongoDB instance
  • PORT
    The port on which the WebSocket service should listen on

Running tests

After making changes, you can run the tests for the respective package using the appropriate CLI commands:

API

To run the API tests, run the following command:

npm run start:e2e:api

The tests create a new instance of Novu and a test db and run the tests against it. The test db is removed after all tests have finished running.

Web

To run the front end tests for the web project using cypress you need to install localstack. The cypress tests perform E2E tests. To be able to perform E2E tests, you need to run the API service in the appropriate test environment.

Run the services in test env with the following commands:

npm run start:e2e:api
npm run start:ws:test

Run the cypress test suite with the following command:

cd apps/web && npm run cypress:run

To open the cypress management window to debug tests, run the following commands:

cd apps/web && npm run cypress:open

Different ports used by the services the project spins up

  • 3000 - API
  • 3002 - WebSocket service
  • 4200 - Web Management UI
  • 4500 - Iframe embed for notification center

Testing providers

To run tests against the providers folder, you can use the npm run test:providers command.