Skip to main content

​
NPM Installation Guide

This guide covers NPM installation for React applications. For non-React applications or simple script tag integration, see the CDN Installation Guide.

​
Installation Methods

The Moss SDK offers two installation methods:
MethodBest ForSetup Complexity
CDN InstallationNon-React apps, simple integration⭐ Simple
NPM Installation (this guide)React apps, full TypeScript support⭐⭐ Moderate

​
Prerequisites

  • A React application (v17 or higher)
  • An active Node.js environment (v16 or higher recommended)

​
1. Authenticating to GitHub Packages

The Moss SDK is hosted as a private package on GitHub. To install it, you must first authenticate your package manager (npm, pnpm, or yarn) to the GitHub Packages registry.

​
Creating a Personal Access Token (PAT)

  1. Navigate to Personal access tokens in your GitHub developer settings.
  2. Click Generate new token and select Generate new token (classic).
  3. Give your token a descriptive name (e.g., moss-sdk-access).
  4. Set the Expiration for the token. For security, avoid “No expiration” in production environments.
  5. Under Select scopes, check the read:packages scope. This grants permission to download packages from the GitHub Packages registry. GitHub Token Scopes
  6. Click Generate token.
  7. Important: Copy the generated token immediately. You will not be able to see it again.

​
Configuring Your Package Manager

You need to create or update a .npmrc file in the root of your project. This file tells your package manager how to handle packages from the @principles-first scope. Create a file named .npmrc in your project’s root directory and add the following line:
.npmrc
@principles-first:registry=https://npm.pkg.github.com/
Next, you need to configure the authentication token for this registry. This is typically done by adding a line to your user-level .npmrc file to keep your token secure.
  • For macOS/Linux: The file is located at ~/.npmrc.
  • For Windows: The file is located at C:\Users\YOUR_USERNAME\.npmrc.
Open this file and add the following line, replacing YOUR_PAT with the Personal Access Token you just created: 
//npm.pkg.github.com/:_authToken=YOUR_PAT
Do not commit your .npmrc file if it contains an authentication token. Add it to your .gitignore file to avoid exposing your credentials.

​
2. Installing the SDK

Once your environment is authenticated, you can install the Moss SDK using your preferred package manager. 
npm install @principles-first/moss-sdk
or 
pnpm add @principles-first/moss-sdk
or 
yarn add @principles-first/moss-sdk

​
3. Integration

After installation, you can integrate the SDK into your application as described in the Quickstart Guide. If you encounter any issues, double-check that your Personal Access Token is not expired and has the correct read:packages scope.

​
Alternative: CDN Installation

If you prefer a simpler setup or don’t use React, consider the CDN Installation method: 
<!-- One-line installation -->
<script src="https://cdn.moss.ai/moss-sdk@latest?applicationId=YOUR_APP_ID"></script>
This method requires no build tools, package managers, or React dependencies.