95 lines
2.5 KiB
Markdown
95 lines
2.5 KiB
Markdown
# Package runtimes and automatic assets
|
|
|
|
## User experience
|
|
|
|
Installing an advanced package should be enough:
|
|
|
|
```bash
|
|
bun add @wrnexus/captcha
|
|
```
|
|
|
|
Then use its component:
|
|
|
|
```wrn
|
|
<Captcha type="number" action="signup" />
|
|
```
|
|
|
|
The user does not copy JavaScript, add a public asset, add a script tag, or duplicate the component.
|
|
|
|
## Declaring a package plugin
|
|
|
|
```json
|
|
{
|
|
"name": "@example/maps",
|
|
"wrnexus": {
|
|
"plugin": {
|
|
"plugin": "./src/plugin.ts",
|
|
"export": "default",
|
|
"factory": true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
```ts
|
|
import { definePlugin } from "@wrnexus/plugin";
|
|
|
|
export default function mapsPlugin() {
|
|
return definePlugin({
|
|
name: "@example/maps",
|
|
componentDirs: [new URL("../components", import.meta.url).pathname],
|
|
clientRuntimes: [
|
|
{
|
|
id: "maps",
|
|
entry: new URL("../client/maps.ts", import.meta.url).pathname,
|
|
type: "module",
|
|
load: "defer",
|
|
singleton: true,
|
|
},
|
|
],
|
|
styleSources: [
|
|
{
|
|
id: "maps-components",
|
|
source: new URL("../components", import.meta.url).pathname,
|
|
},
|
|
],
|
|
});
|
|
}
|
|
```
|
|
|
|
The rendered component declares:
|
|
|
|
```html
|
|
<div data-wrnexus-runtime="maps"></div>
|
|
```
|
|
|
|
## Development behavior
|
|
|
|
- Runtime URL defaults to `/__wrnexus/assets/maps.js`.
|
|
- JavaScript files can be served directly.
|
|
- TypeScript/TSX entries are bundled for the browser.
|
|
- MIME type is JavaScript and `X-Content-Type-Options: nosniff` is set.
|
|
- Assets use `no-cache` during development.
|
|
- Workspace package sources participate in HMR.
|
|
|
|
## Production behavior
|
|
|
|
- Runtime entries are browser-bundled and minified when required.
|
|
- The emitted filename includes a SHA-256 content hash.
|
|
- The asset is served with an immutable cache policy.
|
|
- The final HTML includes the runtime only when its marker appears.
|
|
- Multiple instances inject one script.
|
|
- Build reports list plugins, runtime chunks, assets, component directories, routes, and migrations.
|
|
|
|
## CSR navigation
|
|
|
|
Before replacing `#app`, WRNexusJS calls package `unmount` hooks for runtimes used by the current content. It imports script attributes from the fetched document, loads missing chunks once, then calls `mount` for the new page.
|
|
|
|
## Security requirements
|
|
|
|
- Runtime and asset IDs are validated.
|
|
- Duplicate IDs and public paths fail startup/build.
|
|
- Local package asset paths cannot contain traversal segments.
|
|
- Production builds do not rely on application public-directory copies.
|
|
- Secrets must remain server-side; browser runtimes receive only public configuration and one-use response tokens.
|