Skip to main content

JavaScript for Functions

You can write your functions in JavaScript. This guide describes the process of building a Shopify Function using JavaScript or TypeScript.

Caution

For prototyping ideas, JavaScript is a good starting point if you're familiar with the language. However, expect to run into instruction limits sooner than if you wrote the equivalent function logic in a language that compiles to WebAssembly directly, such as Rust. Shopify strongly recommends Rust.

Anchor to How it worksHow it works

Shopify CLI compiles your JavaScript code using Javy, our JavaScript-to-WebAssembly toolchain. To make development easier, we've also published a Shopify Functions JavaScript library.

Note

To write functions in JavaScript, you must install Node.js 16 or higher. If you previously installed Shopify CLI, then make sure you're using the latest version.

To achieve smaller binary sizes and faster function execution, ensure you are using v3.80.1 or higher of Shopify CLI and v2.0.0 or higher of the @shopify/shopify_function JavaScript package.

Anchor to JavyJavy

Javy is part build tool, and part runtime engine:

  • Build tool: The build tool part takes a JavaScript file and compiles it into a WASI-compatible WebAssembly module, which contains both your code and a full JavaScript engine embedded.

  • Runtime engine: JavaScript by itself is lacking some APIs to meaningfully interact with the environment it is running in. Javy implements a handful of APIs that are required to make JavaScript work well for Shopify Functions.

Anchor to Shopify Functions JavaScript libraryShopify Functions JavaScript library

The Shopify Functions JavaScript library provides convenient functions and hides repetitive boilerplate in your function code. If you create your JavaScript function using Shopify CLI, then it will set up the library for you.

The library includes a TypeScript type generator that inspects your GraphQL query to allow your IDE (Integrated Development Environment) to provide autocomplete suggestions.

Shopify Functions JavaScript library

Read the documentation of our JavaScript library for Shopify Functions.

Anchor to Available JavaScript APIsAvailable JavaScript APIs

Javy and Shopify Functions provide access to the following APIs and globals:

Anchor to ECMAScript 2020ECMAScript 2020

The Javy runtime implements the ECMAScript 2020 specification. However, Javy doesn't enable JavaScript's event loop. This means that async/await and promises will compile fine, but will throw an error when your function executes:

Example error when using the event loop

thread '<unnamed>' panicked at 'called `Result::unwrap()` on an `Err` value: Adding tasks to the event queue is not supported

Anchor to Javy globalsJavy globals

Javy exposes additional IO globals for reading and writing from STDIO. The javy npm package provides convenience methods over the built-in functions.

Javy also exposes an encoding API which is W3C-compatible, with the following exceptions:

  • Support for UTF-8 encoding exclusively
  • No support for TextEncoderStream or TextDecoderStream
  • No support for TextEncoder.encodeInto
  • No support setting the stream property to true in TextDecoder.decode

Anchor to Not available in Javy or Shopify FunctionsNot available in Javy or Shopify Functions

The following JavaScript APIs aren't available:

  • Web-specific browser APIs such as setTimeout, fetch, crypto, or URL.
    • An exception to this is TextEncoder and TextDecoder, which Javy provides.
  • Node.js-specific globals and imports such as process, node:buffer, node:http, or node:util.

Anchor to JavaScript functions and Shopify CLIJavaScript functions and Shopify CLI

The quickest way to get started with JavaScript for Shopify Functions is to use the Shopify Functions JavaScript library with Shopify CLI.

Shopify CLI helps you scaffold projects and uses ESBuild to preprocess JavaScript and TypeScript. This means that you can install and import npm dependencies, just like you would in regular JavaScript. The dependencies will be bundled before everything gets compiled to WebAssembly.

Shopify CLI also supports TypeScript and type annotations from GraphQL schemas and input queries.

Shopify CLI uses Javy to compile a WebAssembly module that conforms to the WebAssembly requirements, automatically generating exports from targets in the function extension configuration.

Anchor to Compatibility with earlier versionsCompatibility with earlier versions

Shopify CLI provides support for backwards compatibility with API versions 2023-07 and earlier. It uses Javy to compile a WebAssembly module that exports a _start function to conform to previous WebAssembly requirements.

Anchor to Using Javy directlyUsing Javy directly

If you want more control over your function, then you can also use Javy directly with no project boilerplate. The following example shows a minimal Shopify Function that only uses the Javy runtime library and Javy support for exporting functions:

my_function.js

import * as fs from "javy/fs";

export function run() {
const inputData = fs.readFileSync(fs.STDIO.Stdin);
const inputStr = new TextDecoder("utf-8").decode(inputData);
const inputObj = JSON.parse(inputStr);

const outputObj = /* process input_obj somehow */

const outputStr = JSON.stringify(outputObj);
const outputData = new TextEncoder().encode(outputStr);
fs.writeFileSync(fs.STDIO.Stdout, outputData);
}

my_function.wit

package my-function:main

world my-function-world {
export run: func()
}

You can compile the piece of JavaScript to a WASI module using the Javy CLI and then run it using function-runner:

Terminal

npx esbuild my_function.js --bundle --platform=node --format=esm --outfile=my_function_bundle.js
npx javy-cli compile my_function_bundle.js -o function.wasm --wit my_function.wit -n my-function-world
echo '{}' | npx function-runner -f function.wasm --export=run

Anchor to Sample appsSample apps

Explore sample apps that contain functions written in JavaScript.

Discounts

View a sample discounts app that contains functions written in JavaScript.

Payment customizations

View a sample payment customization that contains functions written in JavaScript.

Delivery customizations

View a sample delivery customization that contains functions written in JavaScript.

Anchor to TutorialsTutorials

Learn how to use JavaScript with Shopify Functions by following one of our use case tutorials:

Build a discounts function

Use Shopify Functions to create a new discount type for users.

Create a payments function

Use Shopify Functions to hide a payment option offered to customers at checkout.

Build a delivery options function

Use Shopify Functions to rename a delivery option offered to customers at checkout.

Create server-side validation

Use Shopify Functions to block progress on a checkout when the cart line quantities exceed a limit.

Build fulfillment constraints

Use Shopify Functions to customize fulfillment and delivery strategies.

Build a location rule function

Use Shopify Functions to choose a different order location during checkout.

Anchor to Next stepsNext steps

Was this page helpful?