Codakey
Play
← Back to facebook/nuclide

How to Deploy & Use facebook/nuclide

Nuclide Deployment & Usage Guide

Note: Nuclide is an archived project (facebookarchive/nuclide) originally developed by Facebook. It was built on top of the Atom editor, which has also been discontinued. This guide documents the legacy installation and usage procedures for historical reference and maintenance of existing installations.

1. Prerequisites

System Requirements

  • Operating System: macOS 10.10+ or Linux (Ubuntu 14.04+, CentOS 7+, or equivalent)
  • Windows: Not supported
  • Hardware: Minimum 4GB RAM, 8GB+ recommended for large projects

Required Software

  • Atom Editor (1.17.0 or higher, though 1.40.x was the last tested version before archival)
  • Node.js (6.9+ or 8.x recommended; check package.json engines field for exact version)
  • npm (3.x+) or Yarn (1.x+)
  • Python 2.7 (required for native module compilation via node-gyp)

Optional but Recommended

  • Watchman (Facebook's file watching service): Essential for Mercurial integration and file tree performance
  • Flow (JavaScript type checker): Required for Flow type checking features
  • Mercurial (hg) or Git: For version control integration (Nuclide was originally optimized for Mercurial workflows)

2. Installation

Option A: Install from Atom Package Manager (Recommended for Users)

# Install via apm (Atom Package Manager)
apm install nuclide

# Or install specific version
apm install nuclide@0.0.0

Option B: Build from Source (For Development/Contributing)

# Clone the repository
git clone https://github.com/facebookarchive/nuclide.git
cd nuclide

# Install dependencies
npm install
# OR
yarn install

# Bootstrap the development environment
./scripts/dev/setup

# Link for local development
apm link .

Server Installation (For Remote Development)

If connecting to remote development servers:

# On the remote server, install Nuclide server
npm install -g nuclide

# Or install specific server components
cd nuclide/pkg/nuclide-server
npm install

3. Configuration

Atom Configuration

Add to your ~/.atom/config.cson or use the Settings UI:

"*":
  core:
    customFileTypes:
      "source.ini": [
        ".buckconfig"
        ".flowconfig"
      ]
  nuclide:
    # Enable specific features
    "nuclide-arcanist": {}
    "nuclide-hg-repository":
      enableDiffStats: true
    "nuclide-working-sets":
      saveDirectory: "~/.nuclide/working-sets"

Environment Variables

# Required for Flow integration
export FLOW_BIN=/usr/local/bin/flow

# Optional: Nuclide server port (default: 9090)
export NUCLIDE_PORT=9090

# Optional: Path to Watchman
export WATCHMAN_PATH=/usr/local/bin/watchman

Remote Server Configuration

Create ~/.nuclide/server.json on remote hosts:

{
  "port": 9090,
  "ca": "/path/to/ca.crt",
  "cert": "/path/to/server.crt",
  "key": "/path/to/server.key"
}

Flow Configuration

Ensure your project root contains a .flowconfig:

[ignore]
.*/node_modules/.*

[include]
src/

[libs]
flow-typed/

[options]
module.system=haste

4. Build & Run

Development Mode

# Run Atom in development mode with Nuclide
atom --dev .

# Or open specific project
atom --dev /path/to/project

Building Packages

# Build all packages
npm run build

# Build specific package
cd pkg/nuclide-file-tree
npm run build

# Watch mode for development
npm run watch

Running the Server Locally

# Start Nuclide server (for remote connections)
node ./pkg/nuclide-server/lib/main.js

# Or if installed globally
nuclide-start-server --port 9090 --verbose

Testing

# Run all tests
npm test

# Run Flow type checking
npm run flow

# Run specific package tests
cd pkg/nuclide-hg-repository-client
npm test

5. Deployment

Local Deployment (Atom Package)

Since Nuclide is an Atom extension, "deployment" consists of installing the package:

  1. Production: Install via apm install nuclide on user workstations
  2. Enterprise: Distribute pre-built .atom packages via internal package registries
  3. Version Pinning: Lock versions in ~/.atom/packages/nuclide/package.json to prevent auto-updates

Remote Server Deployment

For teams using Nuclide's remote development features:

Docker Deployment:

FROM node:8-slim
RUN npm install -g nuclide
EXPOSE 9090
CMD ["nuclide-start-server", "--port", "9090"]

Systemd Service (/etc/systemd/system/nuclide-server.service):

[Unit]
Description=Nuclide Server
After=network.target

[Service]
Type=simple
User=developer
ExecStart=/usr/local/bin/nuclide-start-server --port 9090
Restart=always

[Install]
WantedBy=multi-user.target

Platform Recommendations

  • Development Workstations: macOS with Atom + Nuclide package
  • Remote Build Servers: Linux (Ubuntu/CentOS) with Nuclide server
  • CI/CD: Not applicable (Nuclide is an IDE, not a service), though the Flow/Buck integration can be used in CI pipelines

6. Troubleshooting

Common Issues

Atom crashes on startup after Nuclide install

  • Clear Atom's compile cache: atom --clear-window-state
  • Disable incompatible packages (e.g., tree-view, find-and-replace may conflict)
  • Check Atom version compatibility: Nuclide 0.x requires Atom 1.17+

"Windows is not supported" error

  • Nuclide explicitly blocks Windows. Use WSL2 with Linux Atom build, or switch to macOS/Linux.

Flow/Watchman integration not working

# Verify watchman is running
watchman watch-list

# Check Flow server status
flow status

# Restart Flow server
flow stop && flow start

Remote server connection failures

  • Verify port 9090 (or configured port) is open: telnet server 9090
  • Check server logs: ~/.nuclide/nuclide.log
  • Ensure SSL certificates are valid if using secure mode
  • Verify Node.js version matches between client and server

Mercurial repository not detected

  • Install hg and ensure it's in PATH
  • Check that .hg directory exists at project root
  • Verify nuclide-hg-repository package is enabled in Atom settings

Build failures (node-gyp errors)

  • Ensure Python 2.7 is installed: python --version
  • Install build essentials:
    • macOS: xcode-select --install
    • Ubuntu: sudo apt-get install build-essential
  • Clear npm cache: npm cache clean --force

Performance Issues

  • Disable unused Nuclide features via Settings → Packages → Nuclide
  • Increase Atom's memory limit: atom --max-old-space-size=4096
  • Ensure Watchman is running (reduces CPU usage for file watching)

Debug Logging

Enable verbose logging:

# Client side
atom --dev -f > nuclide-client.log 2>&1

# Server side
nuclide-start-server --verbose --log-level=DEBUG

Legacy Migration

If migrating from Nuclide to modern alternatives:

  • VS Code: Use the Atom Keymap extension and Flow/ReasonML extensions
  • Flow: Continue using flow-bin directly in terminal
  • Mercurial: Nuclide's Hg features can be replaced with VS Code's built-in Git integration or Mercurial extensions

Support Status: As an archived project, no official support is available. Refer to the Facebook Archive for historical issues and documentation.

← Project overviewView alternatives to facebook/nuclide →