Required dependencies

npm install @babel/core @babel/preset-env @babel/preset-typescript \
  @date-fns/tz @fontsource-variable/open-sans @formatjs/intl \
  @gfx/zopfli @koa/bodyparser @sentry/browser @sentry/core \
  @sinonjs/fake-timers @types/postcss-import \
  @uppy/core @uppy/dashboard @uppy/image-editor @uppy/tus @uppy/utils \
  @zxcvbn-ts/core @zxcvbn-ts/language-common @zxcvbn-ts/language-en \
  altcha autosize babel-loader babel-plugin-formatjs blueimp-md5

npm install --save-dev \
  @eslint/eslintrc @eslint/js confusing-browser-globals eslint \
  eslint-config-prettier eslint-plugin-astro eslint-plugin-formatjs \
  eslint-plugin-import eslint-plugin-mdx eslint-plugin-no-jquery \
  eslint-plugin-promise eslint-plugin-unicorn globals stylelint \
  stylelint-config-standard stylelint-high-performance-animation \
  prettier prettier-plugin-astro typescript typescript-eslint

Python (3.11+) environment:

pip install django psycopg2-binary boto3 pika stripe requests \
  django-two-factor-auth django-scim2 orjson
# See requirements/ directory for the full pinned list

No native iOS/Android linking required. PGroonga requires a PostgreSQL extension installed at the OS level (sudo apt install postgresql-pgroonga).

Project setup

1. Copy source/ into your project root or a subdirectory, e.g. ./zulip-src/.
2. Install Node dependencies from the workspace root using pnpm (required; npm workspaces also work):

   corepack enable
   pnpm install
   

3. Extend tsconfig.json from the provided root config:

   {
     "extends": "./zulip-src/tsconfig.json",
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {"~/*": ["./zulip-src/web/src/*"]}
     }
   }
   

4. Wire ESLint by importing the provided flat config:

   // eslint.config.js in your project
   import zulipConfig from "./zulip-src/eslint.config.js";
   export default [...zulipConfig];
   

5. Set required environment variables:

   DJANGO_SETTINGS_MODULE=zproject.settings
   SECRET_KEY=<random 50-char string>
   DATABASE_URL=postgres://zulip:password@localhost/zulip
   REDIS_URL=redis://localhost:6379
   

6. Run Django migrations and initial setup:

   python manage.py migrate
   python manage.py initialize_voyager_db  # or dev setup script
   

7. Start the dev server:

   python manage.py runserver
   # In parallel: pnpm run dev  (webpack watch)
   

Public API

defineConfig (eslint.config.js)

import {defineConfig} from "eslint/config";
// Returns a flat ESLint config array combining all Zulip rule sets.
const config: ReturnType<typeof defineConfig> = defineConfig([...rules]);

Used when composing your project's ESLint flat config. Wraps the Zulip-opinionated rule set (TypeScript strict, unicorn, formatjs, no-jquery, promise) into a single exportable array. Extend or override individual rule objects after spreading.

prettier.config.js (default export)

import type {Config} from "prettier";
const prettierConfig: Config = {
  bracketSpacing: false,
  trailingComma: "all",
  plugins: ["prettier-plugin-astro"],
  overrides: [
    {files: ["tsconfig.json"], options: {parser: "json5", quoteProps: "preserve"}},
    {files: ["*.md"], options: {embeddedLanguageFormatting: "off"}},
    {files: "*.astro", options: {parser: "astro"}},
  ],
};
export default prettierConfig;

Import or spread into your own prettier.config.js. The bracketSpacing: false and trailingComma: "all" settings are load-bearing for the existing codebase; override only if your project diverges.

stylelint.config.js (default export)

import type {Config} from "stylelint";
const stylelintConfig: Config = {
  extends: ["stylelint-config-standard"],
  plugins: ["stylelint-high-performance-animation"],
  rules: { /* color-no-hex, color-named: never, function-disallowed-list, ... */ },
};
export default stylelintConfig;

Enforces Zulip's CSS conventions: no hex colors, no named colors, no rgb(), no low-performance animations, and HSL-only color values. Use as a base and add project-specific overrides.

Working examples

Scenario - Reuse Zulip ESLint config in a new TypeScript project

Drop the Zulip source alongside your project and extend its flat config, adding a project-specific rule override.

// eslint.config.js (your project root)
import {defineConfig} from "eslint/config";
import zulipBase from "./zulip-src/eslint.config.js";

export default defineConfig([
  ...zulipBase,
  {
    // Project-specific override: allow console in scripts
    files: ["scripts/**/*.ts"],
    rules: {
      "no-console": "off",
      "unicorn/no-process-exit": "off",
    },
  },
]);

Scenario - Adopt Zulip Prettier config with Astro support

Your project uses Astro components. Import Zulip's config to get consistent formatting including the prettier-plugin-astro override.

// prettier.config.js
import zulipPrettier from "./zulip-src/prettier.config.js";
import type {Config} from "prettier";

const config: Config = {
  ...zulipPrettier,
  // Increase print width for your project
  printWidth: 100,
};

export default config;

Run formatting:

npx prettier --config prettier.config.js --write "src/**/*.{ts,tsx,astro,md}"

Scenario - Extend Zulip Stylelint config and add custom property rules

Inherit Zulip's CSS lint rules (no hex, no rgb, performance animation guards) and add a project-specific selector pattern requirement.

// stylelint.config.js
import zulipStyle from "./zulip-src/stylelint.config.js";

export default {
  ...zulipStyle,
  rules: {
    ...zulipStyle.rules,
    // Enforce BEM-like class naming in this project
    "selector-class-pattern": [
      "^[a-z][a-z0-9]*(-[a-z0-9]+)*(__[a-z0-9]+(-[a-z0-9]+)*)?(--[a-z0-9]+(-[a-z0-9]+)*)?$",
      {message: "Expected class selector to follow BEM naming"},
    ],
  },
};

File walkthrough

• .claude/ - AI assistant skill definitions and project-level CLAUDE.md context for Claude-powered dev workflows.
• .github/ - GitHub Actions CI pipelines (lint, test, deploy), issue/PR templates.
• .vscode/ - VS Code extension recommendations for Python, TypeScript, and Prettier.
• analytics/ - Django app tracking server-side usage counts; exposes models and management commands.
• api_docs/ - OpenAPI-based Zulip REST API documentation source files.
• confirmation/ - Handles email confirmation links and token validation for account actions.
• corporate/ - Zulip Cloud billing, plan management, and sponsorship Django app.
• docs/ - Sphinx documentation for contributors and administrators, published to ReadTheDocs.
• locale/ - Gettext .po/.mo files for all translated languages.
• pgroonga/ - SQL migrations and helpers enabling PGroonga full-text search on PostgreSQL.
• puppet/ - Puppet manifests for automated server provisioning and configuration.
• scripts/ - Shell scripts for installation, upgrades, backups, and server maintenance.
• starlight_help/ - Astro/Starlight static site for the Zulip help center (zulip.com/help/).
• static/ - Committed static assets; webpack output lands in static/webpack-bundles/.
• templates/ - Django Jinja2 templates for email, server-rendered pages, and error pages.
• tools/ - Developer scripts: lint, test-backend, test-js-with-node, provision, etc.
• web/ - All frontend source: TypeScript modules, SCSS, Handlebars templates, webpack config.
• zerver/ - Core Zulip Django app: user/message/stream models, views, webhooks, tests.
• zilencer/ - Remote server stats collection and mobile push notification relay app.
• zproject/ - Django settings (dev/prod/test), root URL conf, WSGI/ASGI handlers.
• eslint.config.js - Flat ESLint config; single source of truth for all JS/TS lint rules.
• stylelint.config.js - Stylelint config enforcing Zulip's strict CSS conventions.
• prettier.config.js - Prettier formatting config with Astro and JSON5 support.
• manage.py - Standard Django management entry point.
• package.json - Root Node.js manifest declaring all frontend dependencies and scripts.
• pyproject.toml - Python tool config: ruff linter, mypy type checker, pytest settings.
• version.py - Single source of truth for the Zulip server version string.

Common pitfalls and fixes

• pnpm required, not npm: The workspace uses pnpm-workspace.yaml; running npm install at root silently misses workspace packages. Fix: corepack enable && pnpm install.
• Flat ESLint config requires ESLint 9+: The eslint.config.js uses defineConfig from eslint/config which does not exist in ESLint 8. Fix: npm install eslint@^9.
• prettier-plugin-astro must be installed separately: It is listed as a plugin string, not auto-discovered. Fix: npm install --save-dev prettier-plugin-astro.
• stylelint-high-performance-animation version pin: Versions >=2.0 changed the plugin export format. Fix: pin to stylelint-high-performance-animation@^1 or verify the import shape matches.
• ESM-only config files: All three config files use export default (ESM). If your project uses CJS ("type": "commonjs"), rename them to .mjs or set "type": "module" in package.json.
• Python dependencies not in package.json: The Django backend requirements live in requirements/ Python files, not in Node manifests. Fix: always run both pip install -r requirements/dev.txt and pnpm install during provisioning.

Vibe-coding prompt template

I have dropped the Zulip server source into `./source/` in my project.
I also have USAGE.md describing the block.

Please help me integrate the Zulip toolchain (ESLint, Prettier, Stylelint,
TypeScript config) step by step:

1. Read USAGE.md and source/eslint.config.js, source/prettier.config.js,
   source/stylelint.config.js, and source/tsconfig.json carefully.
2. Install all required Node dependencies listed in USAGE.md ## Required
   dependencies using pnpm.
3. Create or update my project's eslint.config.js to extend the Zulip flat
   config from source/eslint.config.js, adding any project-specific overrides
   I describe below.
4. Create or update prettier.config.js to spread source/prettier.config.js
   and apply my overrides.
5. Create or update stylelint.config.js similarly.
6. Update my tsconfig.json to extend source/tsconfig.json.
7. Add pnpm scripts for lint, format, and typecheck that cover both source/
   and my own src/ directory.
8. Verify no ESM/CJS conflicts exist (all configs must use ESM export default).
9. Show me the final contents of each config file and the updated package.json
   scripts section.

My project-specific requirements: [DESCRIBE YOUR OVERRIDES HERE]

License and credit

Zulip is distributed under the Apache License 2.0. See source/LICENSE for the full text and source/NOTICE for attribution notices. Upstream repository: https://github.com/zulip/zulip.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.