Skip to main content

Introduction 👋

Let's discover CellixJs in less than 5 minutes.

Getting Started​

Get started by exploring the CellixJs platform.

CellixJs is a Domain-Driven Design (DDD) monorepo built on Azure Functions, implementing a modular architecture with strict separation of concerns.

What you'll need​

  • Node.js version 22.0 or above:

    • When installing Node.js, you are recommended to check all checkboxes related to dependencies.

  • Azure Functions Core Tools for local development

    • func --version
      • should return 4.0.6610 or greater
    • Install Guide
      • to upgrade: (mac)
      • brew upgrade azure-functions-core-tools@4

  • MongoDB or access to a MongoDB instance

  • portless local HTTPS proxy support:

    • installed automatically from repo dependencies
    • on first use, trust the local CA when pnpm run dev starts the proxy

Clone and Setup​

Clone the CellixJs repository and set up the development environment:

git clone https://github.com/CellixJs/cellixjs.git
cd cellixjs

Install dependencies and build the project: (we recommend using NVM)

# Install Node.js v22
nvm install v22

# Install Latest NPM (v11+)
nvm install-latest-npm

# Use Node.js v22
nvm use v22

# Clean, install dependencies, and build
npm run clean
npm install 
npm run build

Install VSCode plugins​

You will be prompted to install the recommended VSCode Plugins upon opening the project in VSCode. Go ahead and do so.

Local SonarCloud Analysis​

  • Create a SonarCloud API token from your SonarCloud account
  • Run the following command using your token in the terminal
echo "export SONAR_TOKEN=<your-token>" >> ~/.zshrc
source ~/.zshrc

Local Snyk Security Scanning​

Authenticate Snyk CLI once per machine (login with your GitHub account):

pnpm exec snyk auth

This will open a browser window to authenticate with your GitHub account and grant access to Snyk.

Run security scans before committing code:

# Run all security scans (SCA + SAST + IaC)
pnpm run snyk

# Or run individual scans:
pnpm run snyk:code    # SAST - scan source code for security vulnerabilities
pnpm run snyk:test    # SCA - scan dependencies for vulnerabilities
pnpm run snyk:iac     # IaC - scan Bicep templates for misconfigurations

Expected output for successful scan:

✓ Tested for known issues, no vulnerable paths found.

If vulnerabilities are found:

  • Review Snyk output for vulnerability details and remediation guidance
  • Prioritize by severity: Critical → High → Medium → Low
  • Fix issues using upgrade paths or code refactoring
  • If no fix is available, document in .snyk file (requires CODEOWNERS approval)
  • Re-run pnpm run snyk to verify fixes

Note: Only use the npm scripts listed above. Other Snyk scripts (snyk:monitor, snyk:code:report) are reserved for CI/CD pipeline use only.

Start Development​

Run the development environment:

pnpm run dev

This command will:

  • Stop and start the local portless HTTPS proxy
  • Start Azurite for Azure Storage
  • Launch the API, UI, docs, and mock-service app dev tasks

Builds happen through the Turbo task graph because each app dev task depends on its corresponding build task.

The development server will be available at:

If your browser or OS has not yet trusted the local portless certificate authority, run:

pnpm exec portless trust

Verify Code Quality Locally​

Run all verification steps (lint, build, test, sonarcloud quality gate):

npm run verify

Expected output:

> ...
> Quality Gate passed.

If there are any failing builds, tests, or sonarcloud analysis issues, this command will report them. Please address any issues before pushing code to simulate the CI pipeline and ensure checks will pass on the remote repository.

Note: The verify command requires a valid SONAR_TOKEN environment variable for SonarCloud analysis. See the Local SonarCloud Analysis section for setup instructions.

For security scanning, run Snyk separately:

pnpm run snyk

This runs security scans (SCA, SAST, IaC) to catch vulnerabilities before committing. The CI pipeline will run these scans automatically on PRs and block merges if security issues are found.

Before Committing to a PR​

Both quality gates must pass:

  1. ✅ Snyk security gate: (no vulnerabilities found)
  2. ✅ SonarCloud quality gate: (quality gate passed)

Use the pnpm run verify command locally to ensure both gates pass before pushing code.

If your PR fails a gate in CI/CD:

  • Check the build logs on Azure DevOps to see which issues were detected
  • Rerun pnpm run verify to reproduce the issues locally
  • Fix the issues and push your changes

Architecture Overview​

CellixJs follows these core patterns:

  • Application Packages:

    • API: Azure Functions backend application apps/api
    • UI: React frontend application apps/ui-community
    • Docs: Documentation site using Docusaurus apps/docs

  • Library Packages:

    • Cellix: Core framework and seedwork libraries used across projects packages/cellix/*
    • Ocom: Application-specific libraries used by frontend and backend packages/ocom/*

Open any file in the apps/ or packages/ directory and start exploring: the project uses hot reloading for rapid development!