https://github.com/marko-js/arc-vite
Declaratively bundle and execute code specific to your users using ARC with Vite.
https://github.com/marko-js/arc-vite
Last synced: 5 months ago
JSON representation
Declaratively bundle and execute code specific to your users using ARC with Vite.
- Host: GitHub
- URL: https://github.com/marko-js/arc-vite
- Owner: marko-js
- License: mit
- Created: 2023-11-08T22:30:03.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-28T21:42:47.000Z (7 months ago)
- Last Synced: 2024-12-28T19:02:48.599Z (6 months ago)
- Language: TypeScript
- Size: 406 KB
- Stars: 0
- Watchers: 7
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
arc-vite
Declaratively bundle and execute code specific to your users using [ARC](https://github.com/ebay/arc) and [Vite](https://vitejs.dev).
# Installation
```console
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
```javascript
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:
```js
[
[], // 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`](#optionsflags-string--string) 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`](#optionsflags-string--string) 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:
```js
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
```console
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](https://github.com/eBay/arc/tree/master/packages/arc-server#setflags).
Below is an example of a simple http server that exposes `mobile` arc flag based on the user agent.
```javascript
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](#development)) 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](http://markojs.com) 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.
```javascript
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(`
${assets["head-prepend"] || ""}
${assets.head || ""}
${assets["body-prepend"] || ""}
${assets.body || ""}
`);
}
```
# Code of Conduct
This project adheres to the [eBay Code of Conduct](./.github/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.