Skip to content

Commit 78374a0

Browse files
harmony7harmony7
committed
README updates
1 parent 77e63d3 commit 78374a0

File tree

1 file changed

+52
-75
lines changed

1 file changed

+52
-75
lines changed

‎README.md

+52-75
Original file line numberDiff line numberDiff line change
@@ -1,113 +1,90 @@
1-
# compute-js-static-publish
2-
Static Publisher for Compute@Edge JavaScript
1+
# Static Publisher for Compute@Edge JavaScript
32

4-
Have some static files that you want to serve up on your Compute@Edge service?
5-
6-
Or, easily run your React application generated with [`create-react-app`](https://create-react-app.dev/) on
7-
a [Compute@Edge service](https://developer.fastly.com/learning/compute/javascript/).
3+
Have some static files that you want to serve up on your Compute@Edge service? Have you used a
4+
static site generator to create your next website? Why not deploy and serve it from Fastly's
5+
blazing-fast Edge Computing Platform?
86

97
## How it works
108

119
You have some HTML files, along with some accompanying CSS, JavaScript, image, and font files in a directory.
12-
Or perhaps you have a framework that can generate static output files in a directory.
10+
Or perhaps you have used a framework or static site generator that places output files in a directory.
1311

1412
1. For this example, assume the output files are at `/path/to/files/public` and its subdirectories.
1513

16-
2. When you're ready to deploy the files to Fastly, run `compute-js-static-publish`.
14+
2. Run `compute-js-static-publish`.
1715

1816
```shell
1917
cd /path/to/files
2018
npx @fastly/compute-js-static-publish --public-dir=./public
2119
```
2220

23-
This will generate a Compute@Edge application at `/path/to/files/compute-js`.
24-
It will add a default `./src/index.js` file that serves the static files from your production bundle,
25-
as well as a `./src/statics.js` file that holds references to the files in `/path/to/files/public`.
21+
This will generate a Compute@Edge application at `/path/to/files/compute-js`. It will add a default `./src/index.js` file that serves the static files from your production bundle.
2622

2723
3. Run your application using [Fastly's local development server](https://developer.fastly.com/learning/compute/testing/#running-a-local-testing-server).
2824

29-
```shell
30-
cd ./compute-js
31-
npm install
32-
fastly compute serve
33-
```
34-
35-
4. When you're ready to go live, [deploy it to your Compute@Edge service](https://developer.fastly.com/reference/cli/compute/publish/).
36-
37-
```shell
38-
fastly compute publish
39-
```
40-
41-
5. Each time you build your Compute@Edge project, `compute-js-static-publish` will run a process that scans your `/path/to/files/public`
42-
directory for changes and generates a new `./src/statics.js` file.
43-
44-
You're free to modify the `./src/index.js` handler to suit your needs, such as to add your own API endpoints.
45-
This framework will not touch that file after creation.
46-
47-
## Usage with Create React App
25+
The build process will generate a `./src/statics.js` file that holds references to the files in
26+
`/path/to/files/public`.
4827

49-
`create-react-app` provides a simple-to-use platform for getting started developing React
50-
applications. When you need to deploy your app to the internet, why not deploy it to Fastly's
51-
blazing-fast Edge Computing Platform?
52-
53-
1. Use Create React App to create your application.
54-
55-
```shell
56-
npx create-react-app my-app
57-
```
58-
59-
2. Work on your app as normal.
60-
61-
```shell
62-
cd my-app
63-
npm start
64-
```
65-
66-
3. When you're ready to deploy to Fastly, build your production bundle, then run `compute-js-static-publish`.
67-
68-
```shell
69-
npm run build # create-react-app's build command
70-
npx @fastly/compute-js-static-publish
71-
```
72-
73-
This will make a `compute-js` subfolder and initialize it as a Compute@Edge JavaScript application.
74-
It will add a default `./src/index.js` file that serves the static files from your production bundle.
75-
76-
4. Run your application using [Fastly's local development server](https://developer.fastly.com/learning/compute/testing/#running-a-local-testing-server).
7728

7829
```shell
7930
cd ./compute-js
8031
npm install
8132
fastly compute serve
8233
```
8334

84-
5. When you're ready to go live, [deploy it to your Compute@Edge service](https://developer.fastly.com/reference/cli/compute/publish/).
35+
4. When you're ready to go live, [deploy it to your Compute@Edge service](https://developer.fastly.com/reference/cli/compute/publish/).
8536

8637
```shell
8738
fastly compute publish
8839
```
8940

90-
6. Each time you build your Compute@Edge project, `compute-js-static-publish` will run a process that scans your `./build`
91-
directory for changes and generates a new `./src/statics.js` file.
41+
Each time you build your Compute@Edge project (whether by `fastly compute serve` or `fastly compute publish`),
42+
`compute-js-static-publish` will run a process that scans your `/path/to/files/public` directory and
43+
generates a new `./src/statics.js` file.
9244

93-
You're free to modify the `./src/index.js` handler to suit your needs, such as to add your own API endpoints.
45+
You're always free to modify the `./src/index.js` handler to suit your needs, such as to add your own API endpoints.
9446
This framework will not touch that file after creation.
9547

96-
## Options
48+
## Arguments
49+
50+
Most arguments are optional, and if provided, override the defaults described below.
9751

9852
```shell
9953
npx @fastly/compute-js-static-publish --public-dir=./build --static-dir=./build/static --output=./compute-js --spa
10054
```
10155

102-
| Option | Default | Description |
103-
|---------------|-----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
104-
| `output` | `./compute-js` | The directory in which to create the Compute@Edge application. |
105-
| `public-dir` | `./build` | The directory that contains the application's public files. All files in this directory and subdirectories will be served by your Compute@Edge handler. If not provided, `./build` will be used as the default, and defaults for `create-react-app` will be used assumed. |
106-
| `static-dir` | (None) `./build/static` if `create-react-app` defaults are used | If provided, a subdirectory of `--public-dir` that contains the application's static files. The files in this directory and subdirectories will be cached for 1 year by the browser. Make sure you use a strategy as versioned or cached filenames to avoid stale files. |
107-
| `spa` | `false` | If true, then the Compute@Edge handler will serve `<public-dir>/index.html` when the requested file does not match any of the files in `<public-dir>`. Useful for apps that use [client-side routing](https://create-react-app.dev/docs/deployment#serving-apps-with-client-side-routing). |
108-
| `name` | `name` from package.json, or `compute-js-static-site` | The name of your application. This will be used to fill in the `fastly.toml` and `package.json` files of the generated application. |
109-
| `description` | `description` from package.json, or`Compute@Edge static site` | The description of your application. This will be used to fill in the `fastly.toml` and `package.json` files of the generated application. |
110-
| `author` | `author` from package.json, or `[email protected]` | The author of your application. This will be used to fill in the `fastly.toml` and `package.json` files of the generated application. |
111-
112-
The various configurations will be written to a `static-publish.rc.js` file, and is referenced by the `compute-js-build-static-loader`
113-
command that is run on each `build` of the Compute@Edge project (this runs as a part of the `prebuild` script in `package.json`).
56+
| Option | Default | Description |
57+
|------------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
58+
| `preset` | (None) | Use this argument to select a preset to provide default values for a number of frameworks. See "Frameworks and Static Site Generators" below. |
59+
| `output` | `./compute-js` | The directory in which to create the Compute@Edge application. |
60+
| `public-dir` | (None) | Required. The directory that contains the application's public files. All files in this directory and subdirectories will be served by your Compute@Edge handler. If not provided, `./build` will be used as the default, and defaults for `create-react-app` will be used assumed. |
61+
| `static-dir` | (None) | If provided, a subdirectory of `--public-dir` that contains the application's static files. The files in this directory and subdirectories will be cached for 1 year by the browser. Make sure you use a strategy as versioned or cached filenames to avoid stale files. |
62+
| `auto-index` | `index.html,index.htm` | For a request for a path that ends in a `/`, the handler will attempt to serve the assets identified by appending these names, in the specified order. For example, with the default value of this setting, if `/path/to/a/` is requested, then the handler attempts to serve `/path/to/a/index.html` and `/path/to/a/index.htm`, in that order. |
63+
| `auto-ext` | `.html,.htm` | For a request for a path that does not end in a `/`, if an asset is not found at the path, then handler will attempt to serve the assets identified by appending these extensions, in the specified order. For example, with the default value of this setting, if `/path/to/a` is requested, then the handler attempts to serve `/path/to/a.html` and `/path/to/a.htm`, in that order. |
64+
| `spa` | (None) | If specified, then the handler will serve this file when the requested path does not match any of the known paths, with a 200 code. Useful for apps that use [client-side routing](https://create-react-app.dev/docs/deployment#serving-apps-with-client-side-routing). |
65+
| `not-found-page` | `<public-dir>/404.html` | If specified, then the handler will serve this file when the requested path does not match any of the known paths, with a 404 code. Used to serve up a custom 404 error page.. |
66+
| `name` | `name` from package.json, or `compute-js-static-site` | The name of your application. This will be used to populate the `fastly.toml` and `package.json` files of the generated application. |
67+
| `description` | `description` from package.json, or `Compute@Edge static site` | The description of your application. This will be used to populate the `fastly.toml` and `package.json` files of the generated application. |
68+
| `author` | `author` from package.json, or `[email protected]` | The author of your application. This will be used to populate the `fastly.toml` and `package.json` files of the generated application. |
69+
| `service-id` | (None) | If specified, then this value is used to populate the `serviceId` field of the `fastly.toml` file of the generated application. |
70+
71+
The various configurations will be written to a `static-publish.rc.js` file and appropriate sections of `package.json` and `fastly.toml` of the generated application.
72+
73+
Each time you build the generated application, `compute-js-static-publish` will be run with a special flag `build-static`,
74+
causing it to run in a mode that reads `static-publish.rc.js`, scans the public directory, and recreates `./src/statics.js`.
75+
76+
## Usage with Frameworks and Static Site Generators
77+
78+
`compute-js-static-publish` supports a number of frameworks and static site generators by
79+
applying their default directories and settings. When using a preset, the default values of
80+
each argument are as follows, but you may still override these defaults individually.
81+
82+
| Preset | `public-dir` | `static-dir` | Notes |
83+
|--------------------------------|--------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
84+
| `cra` (or `create-react-app`) | `./build` | `./build/static` | For apps written using [Create React App](https://create-react-app.dev). Checks that the app depends on `react-scripts` to ensure that the app was generated with Create React App. |
85+
| `cra-eject` | `./build` | `./build/static` | Same as `cra`, but does not check for `react-scripts`. Useful for an app that has had `npm run eject` run. |
86+
| `vite` | `./dist` | (None) | For apps written using [Vite](https://vitejs.dev). |
87+
| `sveltekit` | `./dist` | (None) | For apps written using [SvelteKit](https://kit.svelte.dev). |
88+
| `next` | `./out` | (None) | For apps written using [Next.js](https://nextjs.org), using `npm run export`. |
89+
| `gatsby` | `./public` | (None) | For apps written using [Gatsby](https://www.gatsbyjs.com). |
90+
| `docusaurus` | `./build` | (None) | For apps written using [Docusaurus](https://docusaurus.io) |

0 commit comments

Comments
 (0)