ember-repl

ember-repl is an ember-specific integration with repl-sdk providing reactive APIs, test utilities, default module configurations -- making repl-sdk more ergonomic to use in ember projects.

Just like with repl-sdk, all languages and formats can be used in the same project.

Install

With your favorite package manager

Compatibility

  • vite @ ^6+ | only vite-using ember projects are supported
  • ember-source @ ^6.8+
It's possible that other environments and ember-source versions could work, but I don't want to formally spend time figuring out how to support them.

API Overview

The following modules are available:
  • import { ... } from "ember-repl";
  • import { ... } from "ember-repl/test-support";
For deeper understand of what is possible, you'll want to read the source for the real function's method signatures. The full signatures are abbreviated here in this document for brevity.

setupCompiler from ember-repl

This is the main setup method for the compiler -- it allows you to specify default options for the compilers, and define your import-map, allowing you to smoothly use ember-repl for any set of code (even private unpublished code), or entirely unpublished modules. For example, it may be set up in the application's beforeModel hook:
All key-value pairs passed to the second argument of setupCompiler are optional.

In ember-repl some modules are configured for you. These may be reviewed here, in known-modules.ts

compile from ember-repl

Returns a CompileState.
This function takes the CompilerService a text document, and a bag of options, depending on what format is specified (which is required).

Example:

Compiled from ember-repl

Returns a CompileState.
A reactive utility for building dynamic components / render-outputs of an input document. This wraps the above compile function.

Example:
This can also be used in a class:
And there are sufficient overloads to allow reactive class usage via lazy access via arrow functions:

getCompiler from ember-repl

This returns the CompilerService for the given owner -- and if an owner isn't provided, we'll try to call getOwner for you. You are only allowed one compiler for a whole browser document. Example:

type Format from ember-repl

This is the union of all allowed filetype formats. As in what the file extension would be if the provided REPL document were an actual file.

type CompileState from ember-repl

This type is the return value from compile and Compiled. It represents the state and progress of a compile attempt. The important properties on this type:
  • component ComponentLike | undefined

    This is the returned component, if compilation was successful.

  • error Error | undefined

    If an error ocurred, this will be the thrown error.

  • isReady boolean

    indicates if rendering is in progress (false) or if we're ready to render the component (true)

  • format string

    The compiler format used for this compile

  • reason string | undefined

    If an error occurred, this property represents a (hopefully) human readable representation of what happened or what caused the error.

  • isWaiting boolean

    Are we waiting for the compilation attempt to finish? This is more precise than isReady for "completion", because an error also causes isWaiting to flip -- whereas if we have an error, we are not ready (isReady === false) to render.

  • promise Promise

    For imperative usage, you may await the compilation.

setupCompiler from ember-repl/test-support

This test utility should be the main one used for your tests, as it configures each test to start with a clean environment, clear of the main caches. It does not clear the compile cache by default because the same input should always create the same output -- which helps speed up test execution for repeat code samples.
NOTE that this is not needed if your test ultimately runs code that runs the app setupCompiler (descscribed above from the ember-repl import).

Usage:
By default this only provides the basics. For improving test speed, and avoiding hitting the internet during testing, you may want to specify an import map (which allows you to also stub modules):
If you desire to clear the ember-repl compile cache, that can be configured as well:
Lastly, setupCompiler supports configuring the compilers provided by repl-sdk, similarly to how you'd configure the compiler in your actual app code:
If you have a heavy amount of configuration of the compiler in your actual app code, it may be beneficial to extract that configuration to a variable for sharing with this test-support version of setupCompiler

clearCache from ember-repl/test-support

This test utility will clear all the Compliler caches in repl-sdk, but not the caches with ember-repl. These caches include:
  • promise cache
  • request cache
  • tarball cache
Usage:
However, this is not needed if you are using setupComplier.

clearCompileCache from ember-repl/test-support

This test utility will clear the overall compile cache managed by ember-repl It is invoked manually, either in a test, or test lifecycle hook.

Usage: