Skip to content

Commit 4728a22

Browse files
harmony7harmony7
committed
Starting point of migration guide
1 parent 085de0a commit 4728a22

File tree

1 file changed

+3
-257
lines changed

1 file changed

+3
-257
lines changed

‎MIGRATING.md‎

Lines changed: 3 additions & 257 deletions
Original file line numberDiff line numberDiff line change
@@ -5,260 +5,6 @@ are generated during scaffolding. For this reason, it is recommended that you re
55

66
This is straightforward if you're using `compute-js-static-publisher` out-of-the-box. Otherwise, read on.
77

8-
## KV Store
9-
10-
KV Store is no longer optional as of v7
11-
12-
Starting with `v5.0.0`, this tool refers to the KV Store using its finalized product name, "KV Store". References in
13-
code and in configuration that used the previous "Object Store" name have been changed to the new name. If you have
14-
been using the feature, you can take the following steps:
15-
16-
* In your `static-publish.rc.js` file:
17-
* Rename the `objectStore` key to `kvStoreName`. For example, if your KV Store is named `'my-store'`, then change:
18-
```
19-
objectStore: 'my-store'
20-
```
21-
to
22-
```
23-
kvStoreName: 'my-store'
24-
```
25-
26-
* In your `fastly.toml` file, find all lines that pertain to object store entries.
27-
* Such lines may look like this and there may be many:
28-
```toml
29-
[[local_server.object_store.my-store]]
30-
key = "4QEM5nIpyLiNF3wwsbnda5:/404.html_aeed29478691e636b4ded20c17e9eae437614617067a8751882368b965a21bcb"
31-
path = "output/404.html"
32-
```
33-
* Change the `object_store` of these lines to `kv_stores`. For example:
34-
```toml
35-
[[local_server.kv_stores.my-store]]
36-
key = "4QEM5nIpyLiNF3wwsbnda5:/404.html_aeed29478691e636b4ded20c17e9eae437614617067a8751882368b965a21bcb"
37-
path = "output/404.html"
38-
```
39-
40-
## Webpack
41-
42-
Webpack is no longer enabled for new projects
43-
44-
Starting with `v4.0.0` of this tool, webpack is no longer required and is disabled by default for new applications. This can simplify development and result in shorter build times.
45-
46-
You may still wish to use webpack if you need some of the features it provides, e.g., the ability to use loaders, asset modules, module replacement, dynamic imports, etc.
47-
48-
To migrate away from using webpack, make the following changes in your `./compute-js` directory:
49-
50-
* First, check your `webpack.config.js` file to make sure you aren't actually depending on any custom webpack features. When you're ready, continue to the next step.
51-
* Delete `webpack.config.js`.
52-
* Modify `static-publish.rc.js`:
53-
* Change the line `module.exports = {` to `const config = {`
54-
* At the end of the file, add `export default config;`
55-
* In your `package.json` file:
56-
* At the top level, add a `"type"` key if one doesn't already exist, with the value `"module"`.
57-
* Under `devDependencies`, remove the `webpack` and `webpack-cli` entries.
58-
* Under `scripts`, modify the `prebuild` script by removing the `&& webpack` at the end
59-
of it.
60-
* Under `scripts`, modify the `build` script by replacing the parameter `./bin/index.js`
61-
with `./src/index.js`.
62-
* In the end, the two scripts should look like this (along with any other scripts you may have):
63-
```json
64-
{
65-
"prebuild": "npx @fastly/compute-js-static-publish --build-static",
66-
"build": "js-compute-runtime ./src/index.js ./bin/main.wasm"
67-
}
68-
```
69-
70-
If you aren't moving away from webpack just yet, check that your `webpack.config.js` is up-to-date. Refer
71-
to the [default `webpack.config.js` in this package](./resources/webpack.config.js) and add your changes,
72-
or modify your configuration file using the following steps:
73-
74-
* To make the resulting bundle easier to debug, it is recommended to set the `devtool` value to `false`.
75-
76-
* The JavaScript SDK automatically adds the named condition `fastly` when resolving dependency packages.
77-
To match the behavior when bundling with webpack, set `resolve.conditionsNames` to the following:
78-
```
79-
resolve: {
80-
conditionNames: [
81-
'fastly',
82-
'...',
83-
],
84-
],
85-
```
86-
87-
* Starting `v3.0.0`, we depend on `v1.0.0` of the `js-compute` library, which provides namespaced exports for Fastly
88-
features. To use them, you'll need to make the following changes to `webpack.config.js`:
89-
90-
* Set the `target` value to `false`.
91-
92-
* The `output` section should look like this:
93-
```
94-
output: {
95-
filename: "index.js",
96-
path: path.resolve(__dirname, "bin"),
97-
chunkFormat: 'commonjs',
98-
library: {
99-
type: 'commonjs',
100-
},
101-
},
102-
```
103-
104-
* Add a new `externals` array to the bottom if it doesn't exist already. Add the following entry:
105-
106-
```javascript
107-
module.exports = {
108-
/* ... other config ... */
109-
externals: [
110-
/^fastly:.*$/,
111-
],
112-
}
113-
```
114-
115-
* Starting `v3.0.0`, we no longer use webpack static assets to include the contents of static files, and instead [use the
116-
`includeBytes` function](https://js-compute-reference-docs.edgecompute.app/docs/fastly:experimental/includeBytes)
117-
to enable more performant loading, as well as a more size-efficient Wasm binary. As a result, the following code can
118-
safely be removed from the `module.rules` array.
119-
120-
```javascript
121-
{
122-
// asset/source exports the source code of the asset.
123-
resourceQuery: /staticText/,
124-
type: "asset/source",
125-
},
126-
{
127-
// asset/inline exports the raw bytes of the asset.
128-
// We base64 encode them here
129-
resourceQuery: /staticBinary/,
130-
type: "asset/inline",
131-
generator: {
132-
/**
133-
* @param {Buffer} content
134-
* @returns {string}
135-
*/
136-
dataUrl: content => {
137-
return content.toString('base64');
138-
},
139-
}
140-
},
141-
```
142-
143-
If you need webpack for a new project you are scaffolding with this site, specify the `--webpack` command-line option
144-
when you scaffold your application, e.g.:
145-
146-
```
147-
npx @fastly/compute-js-static-publish@latest --webpack --root-dir=./public
148-
```
149-
150-
## Removal of Expressly
151-
152-
Previous versions of `@fastly/compute-js-static-publish` used [Expressly](https://expressly.edgecompute.app) to serve
153-
assets. `v4` does away with this dependency and implements its own server in the `PublisherServer`
154-
class.
155-
156-
When using `v4`, you can remove the dependency on Expressly by deleting the `@fastly/expressly` entry from
157-
`dependencies` or `devDependencies`, in your `package.json` file.
158-
159-
If your application depended on Expressly for things like middleware, you will need to make further
160-
changes.
161-
162-
### The entry point `src/index.js`
163-
164-
As of `v4`, the `src/index.js` entry point no longer uses Expressly, and looks like this:
165-
166-
```js
167-
/// <reference types="@fastly/js-compute" />
168-
import { getServer } from './statics.js';
169-
const staticContentServer = getServer();
170-
171-
// eslint-disable-next-line no-restricted-globals
172-
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
173-
async function handleRequest(event) {
174-
175-
const response = await staticContentServer.serveRequest(event.request);
176-
if (response != null) {
177-
return response;
178-
}
179-
180-
// Do custom things here!
181-
// Handle API requests, serve non-static responses, etc.
182-
183-
return new Response('Not found', { status: 404 });
184-
}
185-
```
186-
187-
If you've previously made changes to `src/index.js`, you will need to make the equivalent changes in this new format.
188-
189-
## `static-publish.rc.js`
190-
191-
This configuration file has changed in v4, and you may find that some features have stopped working after
192-
upgrading from v3.
193-
194-
* In v3, the configuration object was typed `Config`. In v4, it is now typed with a more descriptive name, `StaticPublisherConfig`.
195-
196-
```js
197-
/** @type {import('@fastly/compute-js-static-publish').StaticPublisherConfig} */
198-
const config = {
199-
rootDir: './public',
200-
// ... and so on
201-
};
202-
```
203-
204-
* A new key, `server`, was added to group configurations that pertain to Publisher Server.
205-
206-
To migrate this file, you'll need to make the following changes:
207-
208-
* `publicDir` - rename this to `rootDir`. All files under this root directory will be included by default in the publishing,
209-
except for those that are excluded using some of the following features.
210-
* `excludeDirs`, `includeDirs`, `excludeTest`, `moduleTest` - In v3, these were used in combination to determine whether
211-
each file would be included in the publishing, and whether files would be included as modules. The interaction between
212-
these four tests was not clearly defined, often having one option exclude files, only to have other options add them
213-
back. In addition, in v3 it was not possible to have a module asset that was not also already a content asset.
214-
In v4, these are more clearly defined. These four options should be rewritten in terms of
215-
`excludeDirs`, `excludeDotFiles`, `includeWellKnown`, `contentAssetInclusionTest`, and `moduleAssetInclusionTest`.
216-
* `staticDirs` - in v4, this was renamed to `staticItems` and moved under the new `server` key.
217-
* `spa` - in v4, this was renamed to `spaFile` and moved under the new `server` key.
218-
* `notFoundPage` - in v4, this was renamed to `notFoundPageFile` and moved under the new `server` key.
219-
* `autoExt` - in v4, this was moved under the new `server` key.
220-
* `autoIndex` - in v4, this was moved under the new `server` key.
221-
* `contentTypes` - This is unchanged.
222-
223-
See [static-publish.rc.js config file](./README.md#static-publish-rc) for a detailed explanation of each of these new values.
224-
225-
* `.gitignore`
226-
227-
Depending on the version of `compute-js-static-publisher` used to scaffold your application, your `.gitignore` file
228-
may have been generated with different entries. Add any of the following entries that may be missing from your
229-
`.gitignore` file:
230-
231-
```gitignore
232-
/src/statics.js
233-
/src/statics.d.ts
234-
/src/statics-metadata.js
235-
/src/statics-metadata.d.ts
236-
/src/static-content
237-
```
238-
239-
* Build scripts
240-
* Various versions of `@fastly/compute-js-static-publish` have specified different build scripts. We recommend the following setup, regardless of the version of `@fastly/compute-js-static-publish` or Fastly CLI.
241-
242-
* The build script listed in `fastly.toml` of your `compute-js` directory should look like this:
243-
```toml
244-
[scripts]
245-
build = "npm run build"
246-
```
247-
248-
* If you're using webpack, then the `scripts` section of `package.json` of your `compute-js` directory should contain
249-
the following items (along with any other scripts):
250-
```json
251-
{
252-
"prebuild": "npx @fastly/compute-js-static-publish --build-static && webpack",
253-
"build": "js-compute-runtime ./bin/index.js ./bin/main.wasm"
254-
}
255-
```
256-
257-
* If you're not using webpack, then the `scripts` section of `package.json` of your `compute-js` directory should
258-
contain the following items (along with any other scripts):
259-
```json
260-
{
261-
"prebuild": "npx @fastly/compute-js-static-publish --build-static",
262-
"build": "js-compute-runtime ./src/index.js ./bin/main.wasm"
263-
}
264-
```
8+
> [!NOTE]
9+
> This document is under construction.
10+
>

0 commit comments

Comments
 (0)