zynagent-first application framework

Assets#

Put application assets in src/assets and reference them from templates with literal paths relative to that directory:

<link rel="stylesheet" href="<%= asset('application.css') %>">
<img src="<%= asset('images/logo.svg') %>" alt="">

asset(...) returns a fingerprinted URL under /assets/. This namespace is reserved; invalid references and conflicting routes fail compilation. Asset and template changes trigger development rebuilds.

Stylesheets and scripts#

Global styles go in src/assets/application.css. Zyn combines them with managed template styles into the application stylesheet, even when the source file is absent. See framework/views for template-scoped styles.

CSS bundles local @import rules and rewrites relative url(...) references to fingerprinted asset URLs. Imports must precede body rules; invalid imports and reference cycles fail the build. Other assets retain their logical paths and receive fingerprinted names.

JavaScript is minified in production, but is not bundled or transpiled. Imports are not resolved or rewritten. Use .js for classic scripts and .mjs for modules. Invalid CSS or JavaScript fails the build.

Build profiles#

Zyn selects asset settings automatically for each command:

  • Development: zyn dev, zyn serve, and zyn check leave CSS and JavaScript unminified. zyn serve uses development assets, not production assets.
  • Testing: zyn test also leaves CSS and JavaScript unminified, using a separate set of testing assets.
  • Production: zyn build and deployment minify CSS and JavaScript and prepare compressed files for serving.

During development, browsers revalidate assets before reusing them. In production, browsers can cache assets for a year without revalidation; changed files receive new fingerprinted URLs.

Each profile has its own inventory, so testing and production builds do not replace a running development server's assets. Deployment includes only the production inventory. Published Linux CLIs include the asset compiler; application builds require neither Rust nor Node.

Optimization targets Chrome/Edge 123, Firefox 124, and Safari/iOS Safari 17.4. These targets are fixed, not selected by build date, and do not guarantee compatibility of authored input.

Source maps#

Configure visibility per profile in zyn.zon. The section is optional; omitted profiles keep these defaults:

.assets = .{
    .profiles = .{
        .development = .{ .source_maps = .public },
        .testing = .{ .source_maps = .off },
        .production = .{ .source_maps = .private },
    },
},
  • .off: no generated maps or map links.
  • .private: maps and manifest.json are written to .zyn/source-maps/PROFILE, outside served assets and deployment archives. Assets do not link to them.
  • .public: maps are linked from CSS/JavaScript and served as fingerprinted assets. Public maps expose embedded client sources. Framework-generated template maps exclude server-side scriptlets and other non-style content.

Authored .map files are excluded from public assets in private/off modes. Local and base64 JSON input maps are supported; remote maps are not fetched. Missing or invalid requested maps fail the build. Rebuild after changing map configuration.

Encoded representations#

Production precomputes gzip and Brotli where they reduce file size. The server selects an available representation using Accept-Encoding; compression does not run during requests.