Meta Spark Studio TypeScript Bundler

0.3.0 · active · verified Wed Apr 22

sparkar-bundler is a command-line interface (CLI) tool designed to bundle TypeScript projects specifically for use within Meta Spark Studio. It leverages `esbuild` for high-performance bundling, enabling developers to write Spark AR scripts in TypeScript while benefiting from features like IntelliSense for both Meta Spark API definitions and external Node.js modules. This tool aims to streamline the development workflow by abstracting away complex bundling configurations. Currently at version 0.3.0, it is in active development with a focus on providing a seamless experience for integrating modern JavaScript/TypeScript practices into the Spark AR ecosystem. Its primary differentiator is the specialized handling of Meta Spark API type definitions, which is crucial for developer tooling in a proprietary environment. The release cadence is currently irregular as it's an early-stage project.

Common errors

```
'sparkar-bundler' is not recognized as an internal or external command, operable program or batch file.
```
cause The package was not installed globally, or the global `node_modules` bin directory is not in your system's PATH.

fix Ensure you install the package globally using `npm install -g sparkar-bundler`. Verify your PATH includes the global npm bin directory.
```
Error: Could not find a suitable script target in the project.
```
cause The bundler could not locate a JavaScript file within your Spark AR project's `scripts/` directory that is referenced in the `.arproj` file. Or you did not save the empty JavaScript file after creation in Meta Spark Studio.

fix Open your Meta Spark Studio project, create a new JavaScript script (e.g., `script.js`), save the project, and ensure the script is referenced in the project's properties. Then rerun `sparkar-bundler`.
```
TypeScript compilation error: Cannot find module 'module-name' or its corresponding type declarations.
```
cause The TypeScript source code imports a module that is not installed in the project's `node_modules` or does not have corresponding type definitions.

fix Install the missing module using `npm install module-name` and, if necessary, its type definitions with `npm install --save-dev @types/module-name`.

Warnings

breaking As a pre-1.0 release (v0.3.0), the CLI arguments, configuration file format, and internal project structure assumptions are subject to frequent and breaking changes without prior notice. Backwards compatibility is not guaranteed between minor or even patch versions.
Fix: Always refer to the latest README or GitHub documentation for usage. Pin your CLI tool version or expect to update your workflow with new releases.
gotcha The bundler relies on specific Meta Spark Studio project structures and behaviors. Future updates to Meta Spark Studio could introduce incompatibilities, potentially breaking the bundling process or the execution of bundled scripts.
Fix: Stay informed about Meta Spark Studio updates and check the sparkar-bundler GitHub repository for compatibility notes or required updates to the bundler itself.
gotcha For IntelliSense to work correctly with Meta Spark API, the tool resolves specific type definitions. If these definitions change significantly in a Meta Spark Studio update, IntelliSense might become inaccurate or break until the bundler is updated.
Fix: Report issues on the GitHub repository if IntelliSense stops working after a Meta Spark Studio update. Consider contributing updated type definitions if you identify the changes.

Install

npm install sparkar-bundler npm
yarn add sparkar-bundler yarn
pnpm add sparkar-bundler pnpm

Imports

sparkar-bundler
```
npm install -g sparkar-bundler
```
This package is a global CLI tool, not a library to be imported via `import` or `require` statements in JavaScript/TypeScript code. Its functionality is accessed via the command line after global installation.

Quickstart

Demonstrates the global installation and basic command-line usage to bundle a TypeScript source file into a Meta Spark Studio project.

npm install -g sparkar-bundler

# Navigate into your Meta Spark Studio project directory
cd ~/mySparkProject

# Ensure you have an empty JavaScript file saved in Spark AR Studio
# (e.g., scripts/script.js, ensure it's referenced in the project)

# Run the bundler, it will guide you to select the target script
sparkar-bundler

# The bundled output (e.g., main.js) will be written to your selected script file.
# You should see 'hello, world' (or your script's output) in Meta Spark Studio console.

view raw JSON →