embeddable-sdk

How to use

Configuration

SDK can be configured by defineConfig function as described below.

export default defineConfig({
  plugins: [react],
  pushBaseUrl: "http://localhost:8080",
  previewBaseUrl: "https://app.dev.embeddable.com",
  // Mind the `/` at the end of the audienceUrl. If `/` is not present, the authorization fials with "Service Not Found" error.
  audienceUrl: "https://api.dev.embeddable.com/",
  authDomain: "embeddable-dev.eu.auth0.com",
  authClientId: "xOKco5ztFCpWn54bJbFkAcT8mV4LLcpG",
  errorFallbackComponent: "./src/ErrorHandler.jsx",

  componentsSrc: "./src",
  modelsSrc: "./src/models",
});

| Variable name | Required | Type | Description | Possible values | | ---------------------- | -------- | ------ | -------------------------------------------------- | --------------- | | plugins | Yes | array | Arrays of plugins to use. | react | | pushBaseUrl | No | string | URL of the service for pushing bundles. | URL | | previewBaseUrl | No | string | URL of the service for previewing bundles locally. | URL | | audienceUrl | No | string | URL of the audience used during authentication | URL | | authDomain | No | string | Domain used during authentication | string | | authClientId | No | string | ClientId used during authentication | string | | errorFallbackComponent | No | string | Fallback component in case of an error | string | | componentsSrc | No | string | Path to the components directory | string | | modelsSrc | No | string | Path to the models directory | string |

Publishing

To publish a package you need to use changeset package. It will help you to create a new version of the package and publish it to the registry. By default, the package will be published under next tag.

npx changeset

And select the package you want to publish. It will create a file in .changeset directory with the name like curvy-pandas-reflect.md. You can edit it, change version bump (major|minor|patch) and add a description of the changes. After that, you can commit it and create PR. Once it will be merged to the main, a new PR with bumped version will be created. After it will be merged, the package will be published to the registry under next tag.

Publishing latest version

To publish a latest version of the package, you need to use release branch. Create a PR to the release branch with the changeset file. Once it will be merged, the package will be published to the registry.

Error Logging

The Embeddable SDK implements an error logging system to help diagnose issues during development, building, pushing, and login processes.

Logging Implementation

• All commands (dev, build, push, login) use a centralized logging system.
• Errors are caught and logged both to the console and to a log file.
• Unhandled exceptions and rejections are also captured and logged.

Log File Location

If an error occurs during the execution of any SDK command, detailed error logs are written to:

.embeddable/logs/error.log

Log File Format

The log file contains log entries in JSON format. Each entry is a text string with the following structure:

[timestamp] Command: <command>
Breadcrumbs: <breadcrumbs>
Error: <error>
OS: <os>
Node: <node_version>
SDK Versions: <sdk_versions>
----------------------------------------

Log File Rotation

The log file is rotated when it reaches 5 MB in size. When the log file exceeds this size, the current log file is renamed with a numbered suffix (e.g., error.log.1, error.log.2, etc.), and a new empty log file is created. Up to 5 rotated log files are kept, with the oldest being deleted when a new rotation occurs.

Commands

embeddable:login

Embeddable login command is used to login to the Embeddable platform.

embeddable login

embeddable:build

Embeddable build command is a wrapper around the Vite build command. It will compile the customer's code and log the errors to console.

embeddable build

If host repository is in TypeScript (tsconfig.json is present), the build command will run tsc to check for type errors. If there are any type errors, the build will fail and the errors will be logged to the console.

embeddable build --force

The --force flag will skip the type checking.

embeddable:push

Embeddable push command is used to push the compiled bundle to the Embeddable platform.

embeddable push

embeddable:dev

Embeddable dev command is used to run the customer's code in the development mode.

embeddable dev