RxJS Deployment and Usage Guide

Prerequisites

Node.js: LTS version (18.x or higher recommended)
Yarn: Required instead of npm (see Troubleshooting for details)
Git: For cloning the repository
Modern Browser: Chrome, Firefox, Edge, or Safari (latest versions) for running the documentation site

Installation

Clone the repository:

git clone https://github.com/ReactiveX/rxjs.git
cd rxjs

Install dependencies:
```
yarn install
```
Important: Do not use npm install. This repository uses Yarn workspaces due to conflicting type definitions between @types/jasmine (used by the docs app) and @types/mocha (used by the package).
Verify installation:
```
yarn workspace rxjs test
```

Configuration

Repository Structure

This is a monorepo organized as follows:

/packages/: Contains the RxJS library and related packages
- packages/rxjs/: Main RxJS library source
- packages/observable/: Observable primitives and types
/apps/: Applications
- apps/rxjs.dev/: Documentation site (Angular application)

Branch Strategy

master: Current v8 development (target for most PRs)
7.x: Version 7 maintenance branch
6.x: Version 6 maintenance branch

Build & Run

Development Workflow

Run the RxJS test suite:

yarn workspace rxjs test

Start the documentation site locally:

yarn workspace rxjs.dev start

The docs site will be available at http://localhost:4200 (default Angular dev server port).

Build specific packages:

# Build the main rxjs package
yarn workspace rxjs build

# Build the observable primitives
yarn workspace @rxjs/observable build

Production Build

Build the documentation site for production:

yarn workspace rxjs.dev build

Output is generated in apps/rxjs.dev/dist/ and can be served as static files.

Build all packages:

yarn workspaces run build

Deployment

Publishing the Library (Maintainers)

Version bumping:

yarn workspace rxjs version [patch|minor|major]

Build and publish:

yarn workspace rxjs build
yarn workspace rxjs npm publish

Deploying the Documentation Site

The rxjs.dev application is an Angular static site suitable for deployment to:

Firebase Hosting: Recommended for RxJS official docs

yarn workspace rxjs.dev build
firebase deploy --only hosting

Vercel/Netlify: Connect the repository and set build command to:
```
yarn workspace rxjs.dev build --configuration production
```
Set publish directory to apps/rxjs.dev/dist/rxjs.dev/browser/
GitHub Pages: Build output can be pushed to gh-pages branch

CDN Usage (Consumers)

For production applications consuming RxJS without npm:

<!-- ES Modules -->
<script type="module">
  import { of } from 'https://cdn.jsdelivr.net/npm/rxjs@7/dist/esm/index.js';
</script>

<!-- UMD Bundle -->
<script src="https://cdn.jsdelivr.net/npm/rxjs@7/dist/bundles/rxjs.umd.min.js"></script>

Troubleshooting

"Cannot use npm install"

Problem: TypeScript compilation errors related to conflicting type definitions (@types/jasmine vs @types/mocha).

Solution: Use Yarn exclusively:

rm -rf node_modules package-lock.json
yarn install

Root Cause: npm hoists conflicting type definitions to the root level in workspaces, causing TypeScript to fail when building. See npm RFC #287.

Test Failures in CI vs Local

Problem: Tests pass locally but fail in CI, or vice versa.

Solution:

Ensure you're on the correct branch (master for v8 contributions)
Clear Jest cache: yarn jest --clearCache
Run specific workspace tests: yarn workspace rxjs test --no-cache

Documentation Site Won't Start

Problem: yarn workspace rxjs.dev start fails with Angular errors.