Optimization#

Keywords: minify css, webp optimization, performance tips, assets optimization, compression

Asok includes a built-in optimization engine for production builds.

Build-Time Optimization#

While Asok can minify HTML at runtime during development, the recommended approach for production is to use the asok build command. This performs a one-shot minification of all your templates so the production server can skip this processing.

2. Image Optimization (WebP)#

Asok can automatically convert your images to the modern WebP format.

How it works#

• On-the-fly serving: The static() helper automatically redirects to the .webp version if it exists.
• Auto-Conversion: Images uploaded via the Admin are automatically optimized.
• Standalone Binary: Uses Google's cwebp binary (downloaded into .asok/bin/).

Naming Convention & Rationale (Double Extension)#

When an image like photo.png is optimized, Asok saves it with a double extension (e.g., photo.png.webp). This specific design choice provides several key benefits: - Collision Prevention: If a directory contains both avatar.png and avatar.jpg, compiling both simply to avatar.webp would result in a naming conflict. Retaining the original extension (producing avatar.png.webp and avatar.jpg.webp) ensures each optimized file remains unique. - Source Format Traceability: The framework can instantly identify the original image format from the filename alone. This is essential for serving the original file as a fallback to older clients that do not support WebP, or when IMAGE_KEEP_ORIGINAL=true is enabled. - Stateless Mapping: It avoids the need for an external database or metadata mapping file to link an optimized asset back to its source file.

Quick Start#

Enable it during project creation:

asok create myapp --image

Or add it later:

asok image --enable

Full Scan#

Optimize all existing images in your project:

asok image --optimize

To clean up disk space by removing original files after conversion:

asok image --optimize --delete-originals

Automatic File cleanup#

In production, you can tell Asok to delete original assets right after they are converted during upload:

IMAGE_KEEP_ORIGINAL=false

3. JS & CSS Minification (Esbuild)#

Asok uses the official standalone Esbuild binary to provide ultra-fast minification for your JavaScript and CSS files located in src/partials/.

How it works#

• Performance: Esbuild is written in Go and is significantly faster than Node-based tools.
• Auto-serving: In production (DEBUG=false), the static() helper automatically redirects to the .min.js or .min.css version if it exists.
• Standalone Binary: Downloads into .asok/bin/ with no Node.js required.

Quick Start#

Install the binary:

asok assets --install

Manual Minification#

asok assets --minify

Automatic Build#

The asok preview command automatically runs a minification pass before starting the production server, ensuring all your assets are optimized.

4. Tailwind CSS Minification#

If you use Tailwind CSS, Asok uses the official standalone binary to minify your CSS during production builds.

asok preview
#   Building CSS (minified)...

This runs a one-shot minified build of your src/partials/css/base.css into base.build.css.

5. Gzip Compression#

Asok includes a built-in Gzip middleware to compress HTML, CSS, JS, and JSON responses.

Configuration#

GZIP=true
GZIP_MIN_SIZE=500  # Minimum size in bytes to trigger compression

6. Smart Conditional Asset Injection#

Asok automatically reduces the JavaScript and CSS payload of your pages by only loading the reactive engines and widget-specific assets when they are actually needed.

How it works#

• Scan: During the final rendering phase, Asok performs a lightning-fast scan of your HTML content.
• Triggers: It looks for specific attributes like data-block, data-sse, ws-*, or data-asok-component.
• Injection:
• The Reactive Engine is only injected if data-* attributes are found.
• The Alive Engine (WebSockets) is only injected if ws-* or component attributes are found.
• Result: Static pages remain purely static with zero JavaScript overhead, while reactive pages maintain full functionality automatically.

Directives & Widgets Code-Splitting#

To keep reactive pages as lightweight as possible, Asok splits the assets of the reactive directives runtime: - Core Directives Engine (asok_directives.min.js and asok_directives.min.css): Contains only the core reactivity runtime and minimal directive-specific styling (like asok-cloak). - Form Helper Widgets (asok_widgets.min.js and asok_widgets.min.css): Contains all functions and styles for advanced form widgets (signatures, file dropzones, autocompletes, multi-select tags, tree items, toggles, tables, etc.). - Conditional Loading: The form widgets bundle (both JS and CSS) is dynamically injected only if any helper function (e.g. Asok.) or specific widget class/tag (e.g. asok-dropdown, asok-table, asok-toggle, asok-badge, asok-pagination) is detected in the page content. This ensures pages using simple reactive directives do not download the larger widgets bundle.

7. Scoped Assets (Page-specific Optimization)#

Asok allows you to reduce your global CSS and JS payload by isolating page-specific logic and styles.

How it works#

• Granular Loading: Assets are only loaded for the specific page that needs them.
• Inlining: Scoped assets are inlined directly into the HTML response, reducing the number of HTTP requests and improving Time to First Meaningful Paint.
• Isolation: Prevents side-effects and style leakage, ensuring that optimizations on one page don't break others.

See the Scoped Assets Guide for detailed usage.

8. Production Bytecode (.pyc)#

While Asok disables bytecode generation during development to keep your project structure clean, it leverages full bytecode compilation for production deployments via the asok build system.

How it works#

• Pre-compilation: The asok build command compiles all .py files into optimized .pyc files (using optimize=2).
• Source Protection: Original .py files are removed by default in the dist/ folder, creating a locked distribution.
• Fast Execution: Pre-compiled bytecode allows for faster module loading and slightly improved runtime performance.
• Stealth Mode: By running entirely from bytecode, your production environment remains clean and free of source code.

Configuration#

If you specifically need to enable bytecode generation (e.g. for mission-critical performance in production), set the following environment variable:

ASOK_WRITE_BYTECODE=true

Deployment (Production)#

Don't forget to install the required binaries on your production server:

asok image --install
asok tailwind --install