Installing @roku-sdk/* packages from npmjs.com

Stable Roku SDK packages are public npm packages. Install them with pnpm from registry.npmjs.org: no registry override, token, or authentication is needed. No monorepo checkout is required.

The packaged sdk-installation skill, installed by rk update-ai-context, contains the procedure an AI agent follows. This document is the reference for installing the SDK packages in your own app.

Prerequisites

• Node.js 24 or later and pnpm 11
• Access to registry.npmjs.org from your machine or continuous integration (CI) runner

Installing the packages

If package.json already lists the SDK dependencies, run pnpm install. Otherwise, add the packages your app needs:

pnpm add @roku-sdk/rsg-ts @roku-sdk/components @roku-sdk/solid @roku-sdk/tooling

The @roku-sdk/tooling package provides the rk command-line interface (CLI). You can use pnpm exec rk or a package script to run it. You must import the reactive primitives from @roku-sdk/solid, not solid-js. pnpm installs transitive SDK dependencies automatically. You must declare the packages you import directly, the tooling and types your configuration uses, and any required peers.

A consumer package.json

The following package.json file lists the SDK dependencies for an app:

{
    "name": "my-roku-app",
    "version": "1.0.0",
    "private": true,
    "type": "module",
    "scripts": {
        "build": "rk build",
        "dev": "rk dev"
    },
    "dependencies": {
        "@roku-sdk/rsg-ts": "latest",
        "@roku-sdk/components": "latest",
        "@roku-sdk/solid": "latest",
        "@roku-sdk/tooling": "latest"
    },
    "engines": {
        "node": ">=24.0.0"
    }
}

You can use exact versions for deliberate release pins, or a shared semantic versioning (semver) range for the SDK packages released together. You can commit pnpm-lock.yaml for reproducible installs. The latest tag selects the current stable release when resolving a version; it does not keep you on the current major version. You can use pnpm outdated to inspect available updates and pnpm update to update within your ranges.

The app's TypeScript configuration extends the SDK's package alias:

{
    "extends": "@roku-sdk/rsg-ts/tsconfig.json",
    "compilerOptions": {
        "jsx": "preserve",
        "jsxImportSource": "@roku-sdk/solid",
        "types": ["node"]
    },
    "include": ["src/**/*", "roku-config.ts"]
}

Verifying the registry and lockfile

Run the following commands to check the registry configuration and the installed packages:

pnpm config get registry
# Expected default: https://registry.npmjs.org/
pnpm config get @roku-sdk:registry
# No scope override is needed; an unset value uses the default registry.
pnpm view @roku-sdk/rsg-ts version --registry https://registry.npmjs.org
pnpm list @roku-sdk/rsg-ts @roku-sdk/components

Check the installed versions against the @roku-sdk/* entries in pnpm-lock.yaml. Packages should resolve from registry.npmjs.org. Older lockfile formats may record explicit tarball hosts; current pnpm lockfiles usually store a version and integrity hash, with the registry supplied by configuration rather than a URL. Absence of a host string is not a failure. If an entry has an explicit non-public tarball URL, it still points elsewhere: remove the obsolete registry override and refresh the lockfile with pnpm install --registry https://registry.npmjs.org, then review the diff. You must not hand-edit integrity hashes or add tarball URLs to the lockfile.

Packages on their own version line

Some packages, such as @roku-sdk/flex-grid, have an independent major version line. Older-line patches are staged with a minor-line tag such as latest-2.16; you should check the published tags before you use one:

pnpm view @roku-sdk/flex-grid dist-tags
pnpm add @roku-sdk/flex-grid@latest

FlexGrid 3.x is current and owns latest. For an older line, you can use a semver range such as ^2.0.0, which cannot select 3.x regardless of which line owns latest. The 2.x maintenance tag is maintenance-2x; you must not assume latest-2 exists for every package. Before you change major versions, see Upgrade notes and the package's BREAKING_CHANGES.md for more information.

Your app must declare FlexGrid's six peer dependencies: @roku-sdk/common, @roku-sdk/components, @roku-sdk/interfaces, @roku-sdk/navigation, @roku-sdk/runtime, and @roku-sdk/solid. They ensure the app shares one reactive runtime. Each release sets its peer floors to the SDK version it was built and tested with; inspect them with pnpm view @roku-sdk/flex-grid peerDependencies and upgrade the six together to satisfy those ranges. Other SDK packages released together should keep a shared version range; FlexGrid's separate major is not the SDK's major.

CI

Public installs do not need any npm authentication or CI token. Use the same supported Node.js and pnpm versions and the same committed lockfile as local development:

pnpm install --frozen-lockfile

The runner must be able to reach registry.npmjs.org. A 401 for a public SDK package means the runner is using unexpected registry or authentication configuration, not that a new read token is required.

Troubleshooting

The following table lists common symptoms and what to check: