Step-by-Step Guide to building a custom automated asset optimization manager block for Gutenberg using Svelte standalone templates
Project Setup: SvelteKit, WordPress Integration, and Asset Management
This guide details the construction of a custom Gutenberg block for WordPress, leveraging SvelteKit for its frontend logic and asset optimization capabilities. We’ll focus on a “standalone template” approach within SvelteKit, minimizing framework overhead and maximizing control over the build process for integration into WordPress.
Our objective is to create a block that allows users to select specific assets (images, scripts, stylesheets) associated with a post or page and control their loading behavior (e.g., defer, async, conditional loading) to improve page performance. This requires a robust backend in WordPress to manage asset associations and a frontend component in Gutenberg to interact with these settings.
SvelteKit Project Initialization and Configuration
First, we initialize a SvelteKit project. For this specific use case, we’ll opt for a minimal setup. The key is to configure SvelteKit to output static assets that can be easily enqueued by WordPress.
Run the following command to create a new SvelteKit project:
npm create svelte@latest my-gutenberg-block cd my-gutenberg-block npm install
During the setup, choose the “Skeleton project” template and select “TypeScript” if you prefer, though JavaScript is also fully supported. For this guide, we’ll assume JavaScript. Crucially, we will not be using SvelteKit’s server-side rendering (SSR) or routing features for the block’s frontend logic. We’ll treat it as a static asset builder.
Modify your svelte.config.js to ensure the build output is suitable for WordPress enqueueing. We’ll configure the adapter to output static files.
import adapter from '@sveltejs/adapter-static';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
/** @type {import('@sveltejs/kit').Config} */
const config = {
preprocess: vitePreprocess(),
kit: {
adapter: adapter({
pages: 'build', // Output directory for static pages (not strictly used for block assets)
assets: 'build', // Output directory for static assets
fallback: null // No fallback page needed for block assets
}),
paths: {
base: '/wp-content/plugins/your-plugin-name/assets/js' // This will be adjusted during the build process
}
}
};
export default config;
The paths.base configuration is a placeholder. We will dynamically set the correct public path during the WordPress enqueueing phase. For the build output, we’ll direct SvelteKit to place compiled assets in a specific directory that WordPress can access.
Developing the Svelte Component for the Block
Let’s create a simple Svelte component that will form the core of our Gutenberg block’s interactive elements. This component will manage the selection and configuration of assets.
Create a new file at src/lib/AssetSelector.svelte:
<script>
import { createEventDispatcher } from 'svelte';
export let assets = []; // Array of asset objects { id: string, url: string, type: 'script' | 'style', name: string }
export let selectedAssetIds = []; // Array of IDs of currently selected assets
const dispatch = createEventDispatcher();
function toggleAssetSelection(assetId) {
const index = selectedAssetIds.indexOf(assetId);
if (index === -1) {
selectedAssetIds = [...selectedAssetIds, assetId];
} else {
selectedAssetIds = selectedAssetIds.filter(id => id !== assetId);
}
dispatch('change', { selectedAssetIds });
}
function handleAssetConfig(assetId) {
// In a real scenario, this would open a modal or inline editor
// to configure loading strategies (defer, async, conditional).
console.log(`Configuring asset: ${assetId}`);
// For now, we'll just log.
}
</script>
<div class="asset-selector-wrapper">
<h3>Manage Assets</h3>
<ul>
{#each assets as asset (asset.id)}
<li>
<label>
<input
type="checkbox"
checked={selectedAssetIds.includes(asset.id)}
on:change={() => toggleAssetSelection(asset.id)}
/>
{asset.name} ({asset.type})
</label>
{#if selectedAssetIds.includes(asset.id)}
<button on:click={() => handleAssetConfig(asset.id)}>Configure</button>
</if>
</li>
{/each}
</ul>
</div>
<style>
.asset-selector-wrapper {
border: 1px solid #ccc;
padding: 10px;
margin-bottom: 15px;
}
ul {
list-style: none;
padding: 0;
}
li {
margin-bottom: 8px;
display: flex;
align-items: center;
justify-content: space-between;
}
button {
margin-left: 10px;
padding: 5px 10px;
cursor: pointer;
}
</style>
This component takes an array of available assets and an array of currently selected asset IDs. It allows users to check/uncheck assets and provides a placeholder for configuration. The createEventDispatcher is used to communicate changes back to the parent block component.
Gutenberg Block Registration and Svelte Integration
Now, we’ll register the Gutenberg block in WordPress and integrate our Svelte component. This involves creating a PHP file for the block’s registration and a JavaScript file that will mount our Svelte application.
First, create a WordPress plugin. Let’s assume the plugin slug is custom-asset-manager. Inside your plugin directory (e.g., wp-content/plugins/custom-asset-manager/), create the following structure:
custom-asset-manager/
├── custom-asset-manager.php
├── build/
│ └── block.js
│ └── assets/
│ └── ... (SvelteKit build output)
└── src/
└── lib/
└── AssetSelector.svelte
└── index.js
└── edit.js
└── save.js
The build/ directory will contain the compiled JavaScript and CSS from SvelteKit. The src/ directory will hold our Svelte component and the JavaScript files for Gutenberg integration.
PHP Block Registration (custom-asset-manager.php)
<?php
/**
* Plugin Name: Custom Asset Manager Block
* Description: A Gutenberg block for managing and optimizing assets.
* Version: 1.0.0
* Author: Your Name
*/
function custom_asset_manager_register_block() {
// Automatically load dependencies and version
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/block.asset.php');
wp_register_script(
'custom-asset-manager-block-editor',
plugins_url( 'build/block.js', __FILE__ ),
$asset_file['dependencies'],
$asset_file['version']
);
wp_register_script(
'custom-asset-manager-block-frontend',
plugins_url( 'build/frontend.js', __FILE__ ), // This will be our SvelteKit output for the frontend
array(), // No dependencies for the frontend script itself
$asset_file['version'] // Use the same version for consistency
);
wp_register_style(
'custom-asset-manager-block-editor-style',
plugins_url( 'build/editor.css', __FILE__ ), // Editor-specific CSS
array( 'wp-edit-blocks' ),
$asset_file['version']
);
wp_register_style(
'custom-asset-manager-block-style',
plugins_url( 'build/style.css', __FILE__ ), // Frontend CSS
array(),
$asset_file['version']
);
register_block_type( 'custom-asset-manager/asset-manager', array(
'editor_script' => 'custom-asset-manager-block-editor',
'editor_style' => 'custom-asset-manager-block-editor-style',
'style' => 'custom-asset-manager-block-style',
// We'll handle frontend script enqueueing dynamically based on block presence
) );
}
add_action( 'init', 'custom_asset_manager_register_block' );
// Function to get all registered assets (e.g., from post meta or a custom table)
// This is a placeholder. In a real application, you'd fetch this from post meta.
function custom_asset_manager_get_post_assets( $post_id ) {
$assets_meta = get_post_meta( $post_id, '_custom_assets_data', true );
if ( ! $assets_meta ) {
return array();
}
// Example structure:
// [
// {'id': 'asset-1', 'name': 'Main Script', 'type': 'script', 'url': '/path/to/script.js'},
// {'id': 'asset-2', 'name': 'Hero Image', 'type': 'image', 'url': '/path/to/image.jpg'},
// ]
return json_decode( $assets_meta, true );
}
// Function to get selected assets for a post
function custom_asset_manager_get_selected_assets( $post_id ) {
$selected_assets_meta = get_post_meta( $post_id, '_custom_selected_assets', true );
if ( ! $selected_assets_meta ) {
return array();
}
return json_decode( $selected_assets_meta, true );
}
// Enqueue frontend scripts only when the block is present on the page
function custom_asset_manager_enqueue_frontend_assets( $block_content, $block ) {
if ( 'custom-asset-manager/asset-manager' === $block['blockName'] ) {
// Get current post ID
$post_id = get_the_ID();
if ( $post_id ) {
$selected_asset_ids = custom_asset_manager_get_selected_assets( $post_id );
$all_assets = custom_asset_manager_get_post_assets( $post_id );
// Filter to get only the selected assets
$assets_to_load = array_filter($all_assets, function($asset) use ($selected_asset_ids) {
return in_array($asset['id'], $selected_asset_ids);
});
// Pass data to the frontend script
wp_localize_script( 'custom-asset-manager-block-frontend', 'customAssetManagerData', array(
'assets' => array_values($assets_to_load), // Ensure it's an array
// Add configuration data here if you have it saved per asset
) );
wp_enqueue_script( 'custom-asset-manager-block-frontend' );
}
}
return $block_content;
}
add_filter( 'render_block', 'custom_asset_manager_enqueue_frontend_assets', 10, 2 );
?>
The PHP file registers the block’s editor script and styles. It also includes placeholder functions for retrieving asset data associated with a post. Crucially, it uses the render_block filter to enqueue the frontend script only when the block is present, passing localized data (the selected assets) to it.
Editor Script (src/index.js)
This file will be the entry point for our Gutenberg editor experience. It imports necessary WordPress components and our Svelte component.
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, TextControl, SelectControl, Button } from '@wordpress/components';
import { useState, useEffect } from '@wordpress/element';
import { __ } from '@wordpress/i18n';
// Import our Svelte component. Vite will handle this import.
import App from './App.svelte'; // We'll create this next
// Placeholder for fetching available assets. In a real scenario, this would be an API call
// or fetched via wp_localize_script if the data is static for the editor.
const fetchAvailableAssets = async () => {
// Simulate fetching assets from post meta or a custom API endpoint
// For the editor, we might need to fetch this dynamically.
// For simplicity, let's assume a static list or fetched via REST API.
// In a real plugin, you'd use wp.apiFetch or similar.
return new Promise(resolve => {
setTimeout(() => {
resolve([
{ id: 'asset-1', name: 'jQuery', type: 'script', url: '/wp-includes/js/jquery/jquery.js' },
{ id: 'asset-2', name: 'My Custom Script', type: 'script', url: '/wp-content/themes/your-theme/js/custom.js' },
{ id: 'asset-3', name: 'Main Stylesheet', type: 'style', url: '/wp-content/themes/your-theme/style.css' },
{ id: 'asset-4', name: 'Hero Image', type: 'image', url: '/wp-content/uploads/2023/10/hero.jpg' },
]);
}, 500);
});
};
registerBlockType('custom-asset-manager/asset-manager', {
title: __('Asset Manager', 'custom-asset-manager'),
icon: 'performance', // Choose an appropriate icon
category: 'widgets', // Choose an appropriate category
attributes: {
selectedAssetIds: {
type: 'array',
default: [],
},
// Add other attributes for configuration if needed
},
edit: ({ attributes, setAttributes }) => {
const { selectedAssetIds } = attributes;
const blockProps = useBlockProps();
const [availableAssets, setAvailableAssets] = useState([]);
const [isLoading, setIsLoading] = useState(true);
useEffect(() => {
fetchAvailableAssets().then(assets => {
setAvailableAssets(assets);
setIsLoading(false);
});
}, []);
const handleAssetSelectionChange = (event) => {
setAttributes({ selectedAssetIds: event.detail.selectedAssetIds });
};
// Save the selected assets to post meta
useEffect(() => {
// This effect should ideally be debounced or triggered by a save button
// to avoid excessive writes to post meta.
// For simplicity, we'll save on every change.
const post_id = wp.data.select('core/editor').getCurrentPostId();
if (post_id) {
wp.apiFetch({
path: `/wp/v2/posts/${post_id}`,
method: 'POST',
data: {
meta: {
_custom_selected_assets: JSON.stringify(selectedAssetIds),
},
},
}).then(response => {
console.log('Post meta updated:', response);
}).catch(error => {
console.error('Error updating post meta:', error);
});
}
}, [selectedAssetIds]);
return (
<>
<InspectorControls>
<PanelBody title={__('Asset Configuration', 'custom-asset-manager')} initialOpen={true}>
{isLoading ? (
<p>{__('Loading assets...', 'custom-asset-manager')}</p>
) : (
<App
assets={availableAssets}
selectedAssetIds={selectedAssetIds}
on:change={handleAssetSelectionChange}
/>
)}
</PanelBody>
</InspectorControls>
<div {...blockProps}>
<p>{__('Asset Manager Block', 'custom-asset-manager')}</p>
<p>{__('Configure assets in the Inspector panel.', 'custom-asset-manager')}</p>
{/* You could render a preview here if needed */}
</div>
</>
);
},
save: () => {
// The save function should return null for dynamic blocks
// or render static HTML if the block is static.
// Since we are enqueuing scripts dynamically based on post meta,
// we return null. The PHP `render_block` filter handles the frontend.
return null;
},
});
The src/index.js file registers the block. It uses @wordpress/block-editor and @wordpress/components for the editor interface. The useState and useEffect hooks manage the state of available and selected assets. The InspectorControls provide a sidebar panel where our Svelte component will be rendered. The save function returns null because this is a dynamic block; its frontend rendering and asset enqueueing are handled by PHP.
Main Svelte App Component (src/App.svelte)
This is the main Svelte component that will be mounted within the Gutenberg editor. It acts as a wrapper for our AssetSelector and handles communication with the WordPress editor.
<script>
import AssetSelector from './lib/AssetSelector.svelte';
import { createEventDispatcher } from 'svelte';
export let assets = []; // Available assets
export let selectedAssetIds = []; // Currently selected asset IDs
const dispatch = createEventDispatcher();
function handleSelectionChange(event) {
dispatch('change', event.detail);
}
</script>
<div class="gutenberg-svelte-app">
<AssetSelector
assets={assets}
selectedAssetIds={selectedAssetIds}
on:change={handleSelectionChange}
/>
<!-- Add more controls here for asset configuration (e.g., loading strategy) -->
</div>
<style>
.gutenberg-svelte-app {
font-family: sans-serif;
}
</style>
This App.svelte component simply renders the AssetSelector and forwards the change event. This structure allows for future expansion, such as adding more complex configuration options or different Svelte components within the block’s editor interface.
Build Process and WordPress Enqueueing
To build the SvelteKit project into files that WordPress can use, we need to configure Vite (which SvelteKit uses under the hood) to output the necessary JavaScript and CSS files. We also need to generate a block.asset.php file for WordPress to correctly handle script dependencies and versions.
Vite Configuration for WordPress
Modify your vite.config.js (or create one if it doesn’t exist) to handle the build output correctly. We’ll use a custom plugin to generate the block.asset.php file and ensure the output path is suitable.
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import adapter from '@sveltejs/adapter-static';
import fs from 'fs';
import path from 'path';
// Helper function to generate block.asset.php
function generateAssetFile(pluginDir, version) {
const dependencies = ['wp-blocks', 'wp-element', 'wp-editor', 'wp-components', 'wp-i18n', 'wp-api-fetch'];
const assetFileContent = ` ${JSON.stringify(dependencies)}, 'version' => '${version}' );\n`;
fs.writeFileSync(path.join(pluginDir, 'build/block.asset.php'), assetFileContent);
}
// Helper function to get the current plugin version
function getPluginVersion(pluginDir) {
const pluginFile = fs.readFileSync(path.join(pluginDir, 'custom-asset-manager.php'), 'utf8');
const versionMatch = pluginFile.match(/Version:\s*(.*)/);
return versionMatch ? versionMatch[1] : '1.0.0';
}
export default defineConfig(({ command, mode }) => {
const pluginDir = path.resolve(__dirname); // Assumes vite.config.js is at the root of the plugin
return {
plugins: [
svelte(),
{
name: 'generate-asset-file',
apply: 'build', // Only run during build command
enforce: 'post',
writeBundle() {
const version = getPluginVersion(pluginDir);
generateAssetFile(pluginDir, version);
},
},
],
build: {
outDir: 'build', // Output directory for compiled assets
emptyOutDir: true,
rollupOptions: {
input: {
// Entry points for our scripts
'block': './src/index.js', // Editor script
'frontend': './src/frontend.js', // Frontend script (if needed separately)
},
output: {
entryFileNames: '[name].js',
chunkFileNames: '[name]-[hash].js', // For better caching
assetFileNames: ({ name }) => {
if (name === 'src/index.js' || name === 'src/frontend.js') {
return 'block.js'; // Consolidate editor and frontend JS if desired, or keep separate
}
if (name.endsWith('.css')) {
return 'style.css'; // Main CSS
}
return '[name].[ext]';
},
},
},
},
// Configure SvelteKit adapter if you are using it for more complex builds
// For this standalone approach, Vite's build config is primary.
// If using adapter-static, ensure it's configured correctly in svelte.config.js
// and that the output paths align with what Vite is doing here.
};
});
The custom Vite plugin generate-asset-file hooks into the build process to create the block.asset.php file, which is essential for WordPress to manage script dependencies and versions correctly. The build.rollupOptions.input specifies our entry points, and output defines how the bundled files will be named. We’re consolidating the editor and frontend JavaScript into block.js for simplicity, but you could separate them if needed.
Frontend Script (src/frontend.js)
While the PHP handles the enqueueing, we might need a minimal frontend script to initialize our Svelte component or handle any client-side logic that runs on the actual page. In this setup, the PHP wp_localize_script provides the data, and we can use a simple Svelte app to render it.
// src/frontend.js
import App from './App.svelte'; // Reuse the same App component
// Check if the global data object exists (passed via wp_localize_script)
if (typeof customAssetManagerData !== 'undefined' && customAssetManagerData.assets && customAssetManagerData.assets.length > 0) {
// Find a placeholder element where the Svelte app will mount.
// This element would typically be added by the block's save function or a PHP render callback.
// For dynamic blocks, the PHP render callback is more appropriate.
// However, if we want a Svelte component to render *something* on the frontend,
// we need a hook. Let's assume a div with a specific ID.
const mountPoint = document.getElementById('custom-asset-manager-frontend-app');
if (mountPoint) {
new App({
target: mountPoint,
props: {
assets: customAssetManagerData.assets,
// selectedAssetIds would be derived from the localized data if needed
// For now, we're just displaying the assets passed.
}
});
} else {
console.warn('Custom Asset Manager: Frontend mount point not found.');
}
} else {
// If no assets are selected or data is missing, we might not need to do anything.
// Or, we could log a message if the block is present but has no configured assets.
// console.log('Custom Asset Manager: No assets to load or configure on the frontend.');
}
The frontend.js script checks for the localized data passed by WordPress. If data exists, it attempts to find a mount point (e.g., a div with id="custom-asset-manager-frontend-app") and renders the Svelte App component there. This script will be enqueued by the PHP code when the block is detected.
Running the Build
Execute the build command in your SvelteKit project’s root directory:
npm run build
This command will:
- Compile your Svelte components.
- Bundle JavaScript and CSS files into the
build/directory. - Generate
block.asset.phpin thebuild/directory.
Advanced Asset Optimization Strategies
The current setup provides the framework for selecting assets. To implement actual optimization, we need to extend the block’s functionality and potentially the WordPress backend.
Conditional Loading Logic
Within the AssetSelector.svelte component, you can add controls (e.g., dropdowns, checkboxes) to specify loading strategies for each selected asset:
<!-- Inside AssetSelector.svelte -->
<script>
import { createEventDispatcher } from 'svelte';
export let assets = [];
export let selectedAssetIds = [];
export let assetConfigurations = {}; // { assetId: { loadStrategy: 'defer' | 'async' | 'normal' } }
const dispatch = createEventDispatcher();
function toggleAssetSelection(assetId) {
// ... (existing logic) ...
dispatch('change', { selectedAssetIds, assetConfigurations });
}
function updateAssetConfiguration(assetId, config) {
assetConfigurations = {
...assetConfigurations,
[assetId]: { ...assetConfigurations[assetId], ...config }
};
dispatch('change', { selectedAssetIds, assetConfigurations });
}
</script>
<div class="asset-selector-wrapper">
<h3>Manage Assets</h3>
<ul>
{#each assets as asset (asset.id)}
<li>
<label>
<input
type="checkbox"
checked={selectedAssetIds.includes(asset.id)}
on:change={() => toggleAssetSelection(asset.id)}
/>
{asset.name} ({asset.type})
</label>
{#if selectedAssetIds.includes(asset.id)}
<div class="asset-config">
<label>
Load Strategy:
<select
bind:value={assetConfigurations[asset.id]?.loadStrategy || 'normal'}
on:change={(e) => updateAssetConfiguration(asset.id, { loadStrategy: e.target.value })}
>
<option value="normal">Normal</option>
<option value="defer">Defer</option>
<option value="async">Async</option>
</select>
</label>
</div>
</if>
</li>
{/each}
</ul>
</div>
<style>
/* ... existing styles ... */
.asset-config {
margin-left: 15px;
font-size: 0.9em;
}
.asset-config select {
margin-left: 5px;
}
</style>
The App.svelte and index.js would need to be updated to pass and handle the assetConfigurations attribute. This configuration data would then be saved to post meta alongside the selected asset IDs.
Backend Asset Management
For a robust solution, assets should be managed centrally. This could involve:
- A custom post type or taxonomy to register reusable assets.
- Integration with WordPress Media Library for images.
- A REST API endpoint to fetch available assets for the block editor.
- Saving asset configurations (loading strategy, conditional loading rules) in post meta.
The PHP code would need to be extended to fetch and save this data using register_post_meta and appropriate meta box or REST API handling.
Dynamic Frontend Script Generation
Instead of a static frontend.js, you could dynamically generate a JavaScript file based on the selected assets and their configurations for a specific post. This could be done via a PHP function that outputs a script tag with inline JavaScript, or by generating a unique JS file per post (less scalable).
Example of inline script generation within the render_block filter:
<?php
// Inside custom_asset_manager_enqueue_frontend_assets function
// ... after getting $assets_to_load and $selected_asset_ids ...
$asset_configurations = array(); // Fetch this from post meta
// Example: $asset_configurations = json_decode( get_post_meta( $post_id, '_custom_asset_configs', true ), true );
$script_content = "
(function() {
const assetsToLoad = " . json_encode(array_values($assets_to_load)) . ";
const configurations = " . json_encode($asset_configurations) . ";
assetsToLoad.forEach(asset => {
if (