How-to
Website
Web app
Upgrade a WebFluent 4 project that uses external
Before 4.2, you described JavaScript with external declarations; 4.2 removed them, and the parser now refuses one. wf migrate rewrites a project. This is a page after the migration: it calls a function of a plain script, and places a custom element by its tag:
// Your publishable key, from the Stripe dashboard.
const STRIPE_KEY = "pk_test_123"
page Pricing(path: "/pricing", title: "Pricing", description: "Plans, on a card that leans.") {
Heading("Pricing").h1
Card(mount: (n) => initTilt(n, 10)) { Text("Pro") }
Element("stripe-pricing-table", publishableKey: STRIPE_KEY)
}
The function it calls is the old local module, now a plain script under src/, its export taken off and the declaration's signature written above it as JSDoc:
// src/vendor/tilt.js
/**
* @param {HTMLElement} node
* @param {number} max
*/
function initTilt(node, max) {
node.addEventListener("pointermove", (e) => {
const r = node.getBoundingClientRect();
const x = (e.clientX - r.left) / r.width - 0.5;
node.style.transform = `rotateY(${x * max}deg)`;
});
}
This is the same page as WebFluent 4.1 wrote it, with the module in public/vendor/tilt.js. It is not compiled here, because 4.2 refuses external:
external Tilt from "./vendor/tilt.js" {
fn initTilt(node: Any, max: Number)
}
external element PricingTable("stripe-pricing-table") {
prop publishableKey: String
}
const STRIPE_KEY = "pk_test_123"
page Pricing(path: "/pricing", title: "Pricing", description: "Plans, on a card that leans.") {
Heading("Pricing").h1
Card(mount: (n) => Tilt.initTilt(n, 10)) { Text("Pro") }
PricingTable(publishableKey: STRIPE_KEY)
}
To migrate, run wf migrate in the project. --check writes nothing and says what would change:
$ wf migrate --check
$ wf migrate
How it works
wf migrate takes each external out of the source and puts what it said where 4.2 says it:
- A remote module (
external X from "https://…") becomes ameta.scriptsentry with"module": trueand"as": "X", and itsintegrity:moves tometa.integrity. Its calls keep working, typedJson, since the compiler cannot read a remote file (Load a library from a CDN). - A local module (
external X from "./x.js", a file inpublic/) becomes a plain script at the same path undersrc/, with its exports removed and its signatures as JSDoc.X.f(…)is rewritten tof(…)(Call your own JavaScript). AnAnyin the old signature is written{*}, which reads asJson, so a parameter that takes an element is aT01at the call thatwf migratelists for you: write{HTMLElement}there, as the script above does. - An
external elementcall site becomesElement("tag-name", …), with its arguments and handlers as they were (Place a custom element from a library).
The step lists every .js file already under src/, because each now ships on every page. It runs before wf migrate's other steps, since a file with an external in it does not parse.
Troubleshooting
|
What |
What to do |
|---|---|
|
A module imported a file that is not in |
Put its code in a |
|
A module imports other modules, so it stays in |
Write a script under |
|
A module had an |
It is kept as a plain statement, which names nothing; give the value a name if a page calls it |