 |
VOOZH | about |
|
VOOZH | about |
This document covers StaticForge's deployment and optimization features that prepare sites for production environments. These features handle cache busting, asset optimization, and intelligent file synchronization to remote servers.
For information about generating sitemaps and RSS feeds, see SEO & Discovery Features. For content rendering and processing, see Content Renderers.
StaticForge includes three core deployment and optimization features:
| Feature | Purpose | Event Phase | Priority |
|---|---|---|---|
| CacheBuster | Generates unique build identifiers for cache invalidation | CREATE | 10 |
| TemplateAssets | Copies template CSS/JS to output directory | POST_LOOP | 100 |
| Upload System | Intelligent SFTP sync with incremental updates | UPLOAD_CHECK_FILE | N/A |
These features work together to ensure production deployments are optimized, cacheable, and efficiently synchronized.
Sources:
The CacheBuster feature generates a unique build identifier that enables browser cache invalidation when content changes. It runs during the CREATE event at the highest priority (10) to ensure the build ID is available to all subsequent features.
Sources:
The CacheBuster feature consists of two main components:
The Feature class registers a single event listener for the CREATE event:
The handleCreate() method executes at priority 10 (very early) to ensure the build ID is available during the entire generation pipeline.
Sources:
The service generates a unique build identifier using a timestamp:
This timestamp-based approach ensures:
Sources:
The feature sets two variables in the Container:
| Variable | Format | Example | Usage |
|---|---|---|---|
build_id | Timestamp string | 1704067200 | Direct timestamp access |
cache_buster | Query parameter | sfcb=1704067200 | Template asset URLs |
Sources:
Templates access the cache buster variable to append query parameters to asset URLs:
This ensures browsers fetch fresh assets after each deployment while allowing aggressive caching between deployments.
Sources:
Sources:
The TemplateAssets feature copies CSS, JavaScript, and image files from template directories to the output directory during the POST_LOOP event. This ensures template-specific assets are available in the generated site.
TemplateAssets runs at priority 100 in the POST_LOOP event, after all content has been rendered but before deployment:
Sources:
Templates organize assets in a standard structure:
templates/
└── {TEMPLATE_NAME}/
├── assets/
│ ├── css/
│ │ └── style.css
│ ├── js/
│ │ └── main.js
│ └── images/
│ └── logo.png
└── *.html.twig
TemplateAssets copies the entire assets/ directory to:
output/
└── assets/
├── css/
│ └── style.css
├── js/
│ └── main.js
└── images/
└── logo.png
Sources:
The AssetManager system (documented in Asset Management) allows features to register additional CSS and JavaScript files dynamically. TemplateAssets complements this by ensuring template-specific static assets are available.
Sources:
The upload system provides intelligent SFTP synchronization with incremental updates, hash-based change detection, and plugin extensibility through the UPLOAD_CHECK_FILE event.
Sources:
The upload system maintains a staticforge-manifest.json file on the remote server containing SHA-256 hashes of all deployed files:
This manifest enables:
Sources:
The upload system implements intelligent hash calculation for text files:
For text files (HTML, CSS, JavaScript), the system strips cache buster parameters (?sfcb=...) before hashing. This prevents unnecessary uploads when only the build ID changed but content remains identical.
Sources:
The UPLOAD_CHECK_FILE event fires for each file before SFTP upload, allowing plugins to intercept and handle uploads differently:
| Flag | Type | Purpose |
|---|---|---|
handled | boolean | Set to true if plugin uploaded the file (e.g., to S3) |
skip_upload | boolean | Set to true to skip SFTP upload entirely |
should_upload | boolean | Set to true to force upload even if hashes match |
Sources:
The upload system requires SFTP credentials in .env:
| Variable | Required | Purpose |
|---|---|---|
UPLOAD_URL | Yes | Public URL for production site |
SFTP_HOST | Yes | SFTP server hostname or IP |
SFTP_PORT | No | SFTP port (default: 22) |
SFTP_USERNAME | Yes | SFTP authentication username |
SFTP_PASSWORD | Yes | SFTP authentication password |
SFTP_REMOTE_PATH | Yes | Remote directory path for uploads |
Sources:
The site:upload command orchestrates the entire upload pipeline:
Sources:
This section demonstrates how CacheBuster, TemplateAssets, and the Upload system work together in a complete deployment workflow.
Sources:
The CacheBuster ensures browsers fetch updated content after deployment:
| Deployment | Build ID | Asset URL | Browser Behavior |
|---|---|---|---|
| Initial | 1704067200 | /css/style.css?sfcb=1704067200 | Fetch from server, cache |
| No Changes | 1704067200 | /css/style.css?sfcb=1704067200 | Use cached version |
| After Update | 1704070800 | /css/style.css?sfcb=1704070800 | Cache miss, fetch from server |
This approach provides:
Sources:
The site:render command provides several options for deployment preparation:
The --clean flag removes all files from the output directory before generation:
This ensures:
Sources:
The command supports runtime directory overrides:
These options enable:
Sources:
The --template option allows runtime template selection:
This enables:
.envSources:
Deployment and optimization features use the following configuration:
Sources:
Deployment features do not require configuration in siteconfig.yaml as they use sensible defaults. However, they can be disabled if needed:
Sources:
{{ cache_buster }} in template asset URLsassets/ directory structure.gitignore: Ensure .env is excluded from version controlSources:
Symptom: Asset URLs lack ?sfcb= parameter
Causes:
{{ cache_buster }} variableSolution: Add cache buster to template asset URLs:
Symptom: Template CSS/JS missing from output directory
Causes:
Solution: Verify template structure includes assets/ directory and check file permissions
Symptom: site:upload command fails with connection errors
Causes:
.envSolution: Verify SFTP configuration and test connection manually:
Sources:
Refresh this wiki