Skip to content

INSTALLATION.md

Latest commit

 

History

History
152 lines (107 loc) · 5.88 KB

INSTALLATION.md

File metadata and controls

152 lines (107 loc) · 5.88 KB
Raw

Installation

Roku Dev Studio — setup and build instructions.

Monorepo layout

  • apps/roku-dev-studio/ — Electron desktop app (npm start from repo root runs this workspace).
  • packages/roku-dev-studio-api/ — shared Node API package.
  • packages/roku-dev-studio-remote-server/ — HTTP relay server.

Always run npm install from the repository root so workspaces link correctly.

Quick Start (Development)

  1. Install dependencies (from repo root):

    npm install

  2. Run the app:

    npm start

  3. Optional — verify TypeScript (API, Electron main/preload, HTML renderer modules, remote server, Solid renderer):

    npm run typecheck

    From the repository root; runs all workspace tsc --noEmit targets. The desktop app also transpiles through apps/roku-dev-studio/scripts/build/index.ts (via tsx: main, preload, renderer/dist/).

Building Distributable Apps

For macOS:

npm run build:mac

This creates (under apps/roku-dev-studio/dist/):

  • apps/roku-dev-studio/dist/mac/arm64/Roku Dev Studio-{version}-arm64.dmg — Apple Silicon installer
  • apps/roku-dev-studio/dist/mac/arm64/Roku Dev Studio-{version}-arm64-mac.zip — portable Apple Silicon app

Intel Mac builds are no longer produced by default. To build them locally (deprecated):

npm run build:mac:intel

For Windows:

npm run build:win

This creates (under apps/roku-dev-studio/dist/):

  • apps/roku-dev-studio/dist/win/Roku Dev Studio Setup {version}.exe - Windows installer (x64)
  • apps/roku-dev-studio/dist/win/Roku Dev Studio {version}.exe - Portable Windows app (x64)

For Linux:

npm run build:linux

This creates (under apps/roku-dev-studio/dist/):

  • apps/roku-dev-studio/dist/linux/Roku Dev Studio-{version}.deb - Debian package (x64 & arm64)
  • apps/roku-dev-studio/dist/linux/Roku Dev Studio-{version}-{arch}.AppImage - AppImage (x64 & arm64)

For All Platforms:

npm run build:all

Builds for macOS, Windows, and Linux simultaneously.

Per-platform notes

macOS — code signing & notarization

The mac block in apps/roku-dev-studio/package.json ships with hardenedRuntime: true and notarize: false. By default electron-builder produces a signed-but-not-notarized build if a Developer ID Application certificate is present in your login keychain, and an ad-hoc-signed build otherwise.

If you ship a build without a Developer ID, end users have to clear quarantine before launching:

xattr -cr "/Applications/Roku Dev Studio.app"

To remove that step for end users, set up Apple Developer ID signing + notarization. The full one-time setup (cert generation, App Store Connect API key, GitHub Actions secrets, env-var contract) is captured in .discussion-docs/macos-code-signing-and-notarization.md. Once you have the cert and an app-specific password / API key, set:

export APPLE_ID="you@example.com"
export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
export APPLE_TEAM_ID="ABCDE12345"
# Then build:
npm run build:mac

apps/roku-dev-studio/scripts/notarize.cjs is the afterSign hook that runs @electron/notarize against your build.

Intel Mac builds (opt-in, deprecated)

Default macOS builds target Apple Silicon (arm64) only. Intel/x64 artifacts are not produced in CI. To build them locally:

npm run build:mac:intel

Or, from apps/roku-dev-studio/:

npx electron-builder --mac dmg:x64 zip:x64

Windows

The win target builds an NSIS installer and a portable .exe for x64. No code signing is configured by default — Windows will show a SmartScreen warning until you add an Authenticode certificate (win.certificateFile + win.certificatePassword, or an EV cert in a hardware token).

Cross-building Windows artifacts from macOS / Linux requires Wine. The reliable option is to run npm run build:win on Windows (or in a Windows VM / GitHub Actions runner — see RELEASE_SETUP.md).

Linux

The deb target lists the runtime dependencies it needs in package.json → build.deb.depends:

libgtk-3-0  libnotify4  libnss3  libxss1  libxtst6  xdg-utils  libatspi2.0-0  libuuid1

On Debian / Ubuntu users install with:

sudo apt install ./Roku\ Dev\ Studio-*.deb

apt resolves the depends automatically. The AppImage variant is self-contained — chmod +x and run.

To build Linux artifacts, the build host needs the standard build essentials (gcc, make, python3) plus the same shared libraries listed above so electron-builder can stage the bundle.

CI release pipeline

GitHub Actions workflow + secret layout (signing identity, notarization API keys, etc.) is documented in RELEASE_SETUP.md.

Troubleshooting

Connection Issues

  1. Ensure Roku and computer are on the same network
  2. Control by Mobile Apps (ECP): Settings → System → Advanced system settings → Control by mobile apps → Network access. The app supports all four modes:
    • Disabled – Remote control is off; the app shows a warning and blocks remote/keypress areas.
    • Limited – Text input, app launch, and app query work; full remote keypress may not. The app shows an "ECP Limited" badge and adapts.
    • Permissive – Full control; Roku accepts commands only from private network or same subnet. If you see a "Check Network" warning, ensure this computer is on the same subnet.
    • Enabled – Full control on private network addresses.
  3. Firewall: Allow connections on port 8060

Building Issues

  • macOS code signing: For distribution, you'll need an Apple Developer certificate
  • Windows builds on macOS: Use a Windows VM or GitHub Actions
  • Linux builds: Ensure required dependencies are installed (see package.json deb.depends)