Building from Source

Building from Source

Prerequisites

• Node.js 18 or newer, and npm 9 or newer

No Tizen or webOS SDK install is required. The build scripts in packages/build-tizen/ and packages/build-webos/ package the app themselves.

Install

npm install

The repo uses npm workspaces (packages/*), so a single install at the root covers every package.

Samsung (Tizen)

# All three variants in one command
npm run build:tizen:all

# Or individually
npm run build:tizen         # Regular
npm run build:tizen:oblong  # Oblong (512x423 launcher icon)
npm run build:tizen:legacy  # Legacy (Tizen 2.4, no Smart Hub Preview)

The three variants differ only in launcher icon shape and, for Legacy, the Tizen platform level they target. See Installation and Sideloading for which one a given TV needs.

The .wgt this produces is unsigned, and is built exactly the same way as the packages published on the Releases page. Apps2Samsung handles signing and packaging for you at install time, so for normal sideloading you do not need any Samsung tooling or a certificate at all. See Installation and Sideloading.

Signing with your own certificate (optional)

Only needed if you want the build script itself to produce a signed package. It requires the Tizen CLI, a Samsung certificate created with the certificate manager, and a profile in profiles.xml.

Samsung has retired Tizen Studio and no longer offers it for download. Its replacement is the Tizen VS Code extension, which bundles the same CLI and certificate manager. The build script finds either one automatically, so an existing Tizen Studio install keeps working.

npm run build:tizen -- --signed

The script looks for a profile named Moonfin and for author.p12 and distributor.p12 under ~/SamsungCertificate/Moonfin (%USERPROFILE% on Windows). If your setup differs, point it at the right places:

Variable	Purpose
TIZEN_SIGN_PROFILE	Signing profile name (default Moonfin)
TIZEN_CERT_DIR	Folder holding author.p12 and distributor.p12
TIZEN_PROFILES_XML	Full path to your tooling's profiles.xml
TIZEN_CLI	Full path to tizen / tizen.bat
TIZEN_STUDIO_HOME	Tizen tooling install root, if it is somewhere unusual

Without all of certificate, profile and CLI present, the build falls back to an unsigned package and tells you what was missing.

To force the plain unsigned path even when the Tizen CLI is installed:

npm run build:tizen -- --skip-tizen-cli

LG (webOS)

npm run build:webos

Build outputs

Both land in the project root:

• Tizen: Moonfin_Tizen_<Regular|Oblong|Legacy>_<version>.wgt
• webOS: Moonfin_webOS_<version>.ipk

Development servers

npm run dev:tizen   # serves packages/app with REACT_APP_PLATFORM=tizen
npm run dev:webos   # serves packages/app with REACT_APP_PLATFORM=webos

The platform is selected through REACT_APP_PLATFORM, so the dev server exercises the same platform-detection path the packaged app uses. See Development for how that abstraction works.

Note that a browser dev server is subject to CORS restrictions that packaged .wgt and .ipk builds are not, so some server requests behave differently there than on a TV.

Troubleshooting

ClassNotFoundException: org.tizen.ncli.ide.shell.Main, or a path containing \\..\..\..\sdk.info

The Tizen CLI works out where it is installed from the path it was started with, and looks for sdk.info relative to that. If it is started by name rather than by full path, it searches from the wrong folder and cannot load its own libraries. The build script now always calls it by full path, so first make sure you are building from current main. If it still happens, your Tizen tooling is in a location the build script does not know about, and setting TIZEN_CLI to the full path of tizen.bat will fix it. You can also just skip it entirely with --skip-tizen-cli, since the CLI is only used for signing and for installing straight to a TV.

Samsung certificate or profiles.xml not found

These are warnings, not errors. The build continues and produces an unsigned package, which is what you want for normal sideloading. Use the variables in the signing section above if you do want a signed build.

Build fails on Windows

Older versions shelled out to zip, which does not exist on Windows. Packaging is now done in Node with no external tools, so make sure you are building from current main.