How does Quokka work?

Quokka.js has been designed from the ground up to be blazingly fast. Under the covers, Quokka.js performs a number of tricky runtime hacks to allow your code to be run much faster than if not using Quokka.

Depending on your project type, the way that Quokka runs your code may be a little different to what you are used to. Quokka runs your code using node.js regardless of your project type and configuration. In terms of runtime behavior, running your code in node.js is similar to running your browser but there are some important differences. For example, some browser runtime features may be missing (such as window, document, window.fetch), and you don’t have a graphical user interface to interact with; read how to simulate a browser environment.

Quokka’s execution pipeline

In order to run your code and provide results in your editor, Quokka performs the following steps:

1. Transpile your code if required (this happens if you are using Babel or TypeScript).

2. Adjust your code to provide Quokka’s special features (e.g. Live Feedback, Live Code Coverage, Value Explorer, etc.).

3. Execute any Quokka Plugins that have been configured.

4. Execute your code, using the current Quokka file as the entry-point for your program.

5. For imported files:

   a. For project files -> Step 1 will also be applied.

   b. For external dependencies -> Step 1 will not be applied.

There are a couple of important notes to be aware of regarding execution:

• Quokka waits for your program to finish before showing code coverage and inline results. If for example, your code started an HTTP server during execution, you must stop the server before Quokka will show results. Similarly, if you have some long-running asynchronous code, Quokka will wait for it to finish before displaying results. Some results (like logs) will displayed in Value Explorer before the program finishes as they are available.

• By default, Quokka reuses its node process for subsequent executions of your code. This is one of the many things that makes it so fast. On rare occasions, you may need to change this behavior with the recycle setting.

• Remember, Quokka is fast! If you are calling an external API, you might like to use the Run on Save or Run Once features.

Using Quokka on existing projects

Quokka.js is ideally suited for rapid JavaScript and TypeScript prototyping and may be used within your existing projects.

Quokka may not work if you are trying to use code or components that require special runtime initialization, or if you are running code whose runtime is not compatible with node.js.

For example, if you try and run Quokka on a React functional component, while the component will work in the Browser because of React’s browser runtime, no code will be executed by Quokka in node.js:

function Welcome(props) {
  return <h1>Hello, {props.name}</h1>;
}

// Running this code in Quokka does nothing as the
// "Welcome" function is defined but is never called.

Note

The sub-sections under the Guides section on the left provide some additional details, and tips and tricks for how you may use Quokka.js with various runtime environments and configurations.

Express

If you want to run backend code that includes hosting an HTTP server, then you need to ensure that your HTTP server is stopped in order for Quokka to display results. For example:

const server = app.listen(3000);

await awesomeScratchFileCode();

server.close();