arc-vite

Declaratively bundle and execute code specific to your users using ARC and Vite.

Installation

npm install arc-vite

Configuration

The only required configuration for arc-vite is the flags or flagSets option. These limit the number of possible flag permutations and allow arc-vite to optimally bundle your app.

Example vite.config.ts

import { defineConfig } from "vite";
import arcPlugin from "arc-vite";

export default defineConfig({
  plugins: [arcPlugin({ flags: ["mobile"] })],
});

options.flags: (string | string[])[]

An array where each element is either a string or string[]. Each string represents an individual flag, and each array of strings represents a group of flags that can be combined. When a string[] is provided as an item any combination of those flags will become valid. Note that an empty flag combination (the default flags) is always output.

Eg flags: ["legacy", ["tablet", "desktop"]] will yield the following exploded flag sets:

[
  [], // the empty flag set
  ["legacy"],
  ["tablet"],
  ["tablet", "legacy"],
  ["desktop"],
  ["desktop", "legacy"],
];

options.flagSets: string[][]

An array of all possible flag combinations. This is lower level than options.flags and allows you to have complete control over the possible flag combinations. The empty flag set is still required automatically added for you.

Note that arc-vite also exposes a createFlagSets method to create flag combinations similar to options.flags and a hasFlags method to filter the flag sets down. This can be useful to create flag combinations and then filter down unnecessary ones.

Eg lets say that in the above we want to ensure that the tablet flag will never be paired with the legacy flag. Using this helpers and the options.flagSets we could achieve that with the following example:

import { defineConfig } from "vite";
import arcVite, { createFlagSets, hasFlags } from "arc-vite";

export default defineConfig({
  plugins: [
    arcVite({
      // The below will filter out all flagSets which have `tablet` and `legacy`.
      // In this case that means `["tablet", "legacy"]` and `["tablet", "legacy", "experiment"]` will be removed.
      flagSets: createFlagSets([
        "legacy",
        "experiment",
        ["tablet", "desktop"],
      ]).filter((flagSet) => hasFlags(flagSet, ["tablet", "legacy"])),
    }),
  ],
});

options.runtimeId?: string

For inter chunk communication arc-vite uses a global variable in the browser. To avoid conflicts with multiple copies of arc-vite prepared assets loaded into a single page you can provide a valid javascript identifier as a string to use as the global.

Setting arc flags.

Development

In development arc-vite does not currently support runtime adaptive flags. Instead you can configure the current flags to use by setting the FLAGS environment variable with dot (.) separated flags.

Eg when running your vite server

FLAGS=mobile node ./my-server.js

Production

Setting arc flags for production is the same as other implementations of arc. Use arc-server's setFlags api. Below is an example of a simple http server that exposes mobile arc flag based on the user agent.

import https from "https"
import { setFlags } from "arc-server"

https.createServer(..., (req, res) => {
  setFlags({
    mobile: req.getHeader("Sec-CH-UA-Mobile") === "?1"
  });

  // run app code
}).listen(8443);

Note: Setting process.env.FLAGS (as described in the settings flags for development section) will also work for production builds. When set, the actual flags passed to setFlags or withFlags are ignored and instead the process.env.FLAGS are passed. This can be useful to force a flag set to be used in preview environments.

Reading browser assets

If you are using Marko then the following is not necessary since this plugin will communicate with the Marko compiler in order to automatically inline the appropriate assets.

For other types of setups this plugin exposes another top level api on arc-server called getAssets. This method will return an object with html to inject into your application given the currently set arc flags.

import { getAssets } from "arc-server";
export function handleRequest(req, res) {
  const assets = getAssets("index"); // get all assets for the `index` (default) entry into vite.
  res.end(`
<!DOCTYPE html>
<html lang="en">
<head>
  ${assets["head-prepend"] || ""}
  <!-- ... -->
  ${assets.head || ""}
</head>
<body>
  ${assets["body-prepend"] || ""}
  <!-- ... -->
  ${assets.body || ""}
</body>
</html>
  `);
}

Code of Conduct

This project adheres to the eBay Code of Conduct. By participating in this project you agree to abide by its terms.