Installing the Sublay CLI

The Sublay CLI copies fully customizable comment components directly into your project as editable source code. You can use it with npx (no installation required) or install it globally.

Prerequisites

Node.js 20.5+

node --version
# Should output v20.5.0 or higher

A React, React Native, or Expo project

Supported platforms:

React (Web) ✅
React Native ✅
Expo ✅

A Sublay project

Create a project in the Sublay Dashboard if you haven’t already.

Using npx (Recommended)

No installation required — npx always uses the latest version:

npx @sublay/cli init

Global Installation (Optional)

npm install -g @sublay/cli

Then use without npx:

sublay init
sublay add comments-threaded --ref v8

The rest of this documentation uses npx @sublay/cli to stay version-agnostic, but sublay works identically when installed globally.

Initializing Your Project

Run the init command from your project root:

cd your-react-app
npx @sublay/cli init

Interactive Prompts

Platform Selection

Question: “Which platform are you using?”Options: React (Web) · React Native · ExpoDetermines which component variants and dependencies are used.

Styling Preference

Question: “Which styling approach do you prefer?”Options:

Tailwind CSS — Uses utility classes (bg-white dark:bg-gray-800)
Inline Styles — Uses style objects (style={{ backgroundColor: '...' }})

Choose Tailwind if your project already uses Tailwind CSS. Otherwise choose Inline Styles.

Component Path

Question: “Where should components be installed?”Default: src/componentsThe directory where CLI components will be copied. You can use any path.

What Happens During Init

Detects your project type from package.json
Creates sublay.json in your project root
Checks for required peer dependencies and offers to install missing ones

The sublay.json File

After initialization, a sublay.json file is created in your project root:

{
  "platform": "react",
  "style": "tailwind",
  "typescript": true,
  "paths": {
    "components": "src/components"
  },
  "aliases": {
    "@/components": "./src/components"
  }
}

See Configuration for a full reference.

Adding Components

npx @sublay/cli add <component> --ref v8

Option	Description
`--ref <branch>`	The branch of the component registry to read from. Without it, `add` reads the default branch. The v8 components are on the `v8` branch, so every `add` command in this documentation uses `--ref v8`.
`--lang <code>`	The language of the component’s text. Without it, the component is installed in English. See Languages & Right-to-Left for the available codes.

add reads sublay.json, then:

Downloads the component for your platform and style from the chosen branch.
Downloads the shared pieces the component is built from (the GIF picker, avatar, skeletons, icons and similar) into a shared/ folder inside the component’s own folder.
Writes the files to {paths.components}/<component>/, with imports adjusted to the installed layout. If any file fails to download, nothing is written.
Checks your package.json for the packages the component and its shared pieces need, and offers to install the missing ones.

A branch name may contain letters, digits, ., _, - and /. If the branch or the component does not exist on it, add stops with a message naming the one that is missing and writes nothing. Every installed file is yours to edit, the files in shared/ included. Each component gets its own shared/ folder.

Installing Dependencies

add checks for the packages a component needs and prompts to install them if missing. The Sublay SDK for your platform is always one of them: React (Web):

npm install @sublay/react-js

React Native:

npm install @sublay/react-native

Expo:

npm install @sublay/expo

These packages are required. Components use them for data fetching, authentication, real-time updates, and core functionality.

Troubleshooting

Warning: No package.json found

⚠️  No package.json found

After installing a component’s files, add reads your package.json to check which of the component’s dependencies you already have. If there is no package.json in the current directory it prints this warning and skips that check — the component itself is still installed, and the command still succeeds.Run add from your project root (where package.json lives) to get the dependency check.

CLI hangs or doesn't respond

Press Ctrl+C to cancel
Clear npx cache: npx clear-npx-cache
Try again: npx @sublay/cli init

Want to change configuration

Delete sublay.json and run npx @sublay/cli init again, or manually edit the file and re-run add commands.

Overview

Installation

Component Types

Threaded Comments

Social Comments

Notification Control

Customization

CLI Setup

Installing the Sublay CLI

Prerequisites

Using npx (Recommended)

Global Installation (Optional)

Initializing Your Project

Interactive Prompts

What Happens During Init

The sublay.json File

Adding Components

Installing Dependencies

Troubleshooting

Next Steps

Quick Start

Configuration Reference

Threaded Comments

Social Comments

​Installing the Sublay CLI

​Prerequisites

​Using npx (Recommended)

​Global Installation (Optional)

​Initializing Your Project

​Interactive Prompts

​What Happens During Init

​The sublay.json File

​Adding Components

​Installing Dependencies

​Troubleshooting

​Next Steps

Quick Start

Configuration Reference

Threaded Comments

Social Comments

Installing the Sublay CLI

Prerequisites

Using npx (Recommended)

Global Installation (Optional)

Initializing Your Project

Interactive Prompts

What Happens During Init

The sublay.json File

Adding Components

Installing Dependencies

Troubleshooting

Next Steps