diff --git a/docs/dependencies/aliases.md b/docs/dependencies/aliases.md index 01d64f96..ce0b6cc4 100644 --- a/docs/dependencies/aliases.md +++ b/docs/dependencies/aliases.md @@ -14,8 +14,7 @@ When we left [our `lodash` example](/docs/dependencies/npm) we had version `4.17.21` published to the URL `https://eik.store.com/npm/lodash/4.17.21/index.js`. -The `alias` command in the [Eik CLI](/docs/reference/at-eik-cli) -creates a URL that redirects to a specific version of a library. +The [Eik CLI](/docs/reference/at-eik-cli) has an `alias` command that works like so: ```sh eik login --key YOUR_EIK_KEY --server https://eik.store.com @@ -30,7 +29,15 @@ Let's break down the alias command a bit. The `--server` argument lets you run the `login` and `alias` commands without having `eik.json` in the current directory. -Now you should be able to go to `https://eik.store.com/npm/lodash/v4/index.js`, and your browser should be redirected to the version you aliased. +Now you can go to `https://eik.store.com/npm/lodash/v4/index.js` in a browser, and you should be redirected to the version you aliased. + +:::tip + +On servers running `@eik/service` 5.1.0 or newer you can also go to `https://eik.store.com/npm/lodash/~4/index.js` (~4 instead of v4) to get the file directly with [stale-while-revalidate cache headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#stale-while-revalidate), saving the browser from following a redirect. + +This is particularly useful for assets on the critical path, like global CSS and font files. + +::: ## Updating an alias diff --git a/docs/server/http-api.md b/docs/server/http-api.md index 39bc37ce..a6f5daeb 100644 --- a/docs/server/http-api.md +++ b/docs/server/http-api.md @@ -418,12 +418,13 @@ An alias is a shorthand between a major version of a package / import map and th ### Endpoint Summary Table -| Name | Verb | Endpoint | Form Fields | -| ------------------------------------- | ------ | ------------------------------ | ----------- | -| [Public Alias URL](#public-alias-url) | GET | `/:type/:name/v:alias/:extras` | | -| [Create Alias](#create-alias) | PUT | `/:type/:name/v:alias` | `version` | -| [Update Alias](#update-alias) | POST | `/:type/:name/v:alias` | `version` | -| [Delete Alias](#delete-alias) | DELETE | `/:type/:name/v:alias` | | +| Name | Verb | Endpoint | Form Fields | +| ----------------------------------------------------------------------------------- | ------ | ------------------------------ | ----------- | +| [Public Alias URL](#public-alias-url) | GET | `/:type/:name/v:alias/:extras` | | +| [Public stale-while-revalidate alias URL](#public-stale-while-revalidate-alias-url) | GET | `/:type/:name/~:alias/:extras` | | +| [Create Alias](#create-alias) | PUT | `/:type/:name/v:alias` | `version` | +| [Update Alias](#update-alias) | POST | `/:type/:name/v:alias` | `version` | +| [Delete Alias](#delete-alias) | DELETE | `/:type/:name/v:alias` | | ### Public Alias URL @@ -454,6 +455,37 @@ curl -X GET -L http://localhost:4001/pkg/fuzz/v8/main/index.js curl -X GET -L http://localhost:4001/map/buzz/v4 ``` +### Public stale-while-revalidate Alias URL + +**Method:** `GET` + +Available since [`@eik/service@5.1.0`](https://github.com/eik-lib/service/releases/tag/v5.1.0). + +Retrieves files from a package and serves them without a redirect, using [`stale-while-revalidate`](http://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control#stale-while-revalidate). + +```bash +https://:assetServerUrl:port/:type/:name/~:alias/:extras +``` + +URL parameters: + +- `:type` is the type to retrieve from. Validator: `pkg`, `npm` or `img`. +- `:name` is the name of the package. Validator: Comply with [npm package names](https://github.com/npm/validate-npm-package-name). +- `:alias` is the major version of the package, prefixed by tilde (`~`). +- `:extras` whildcard pathname to any file in a package. + +Status codes: + +- `200` if aliased file exist +- `302` if alias exists and `:extras` was not specified (same behavior as [Public Alias URL](#public-alias-url)) +- `404` if alias is not found + +Example: + +```bash +curl -X GET -L http://localhost:4001/pkg/fuzz/~8/main/index.js +``` + ### Create Alias **Method:** `PUT`