Vengala Vinay

Having 12+ Years of Experience in Software Development

Home » Step-by-Step Guide to building a custom broken link checker block for Gutenberg using Svelte standalone templates

Step-by-Step Guide to building a custom broken link checker block for Gutenberg using Svelte standalone templates

Setting Up the Svelte Development Environment

To build a custom Gutenberg block with Svelte, we’ll leverage Svelte’s standalone template capabilities. This approach avoids the need for a full SvelteKit or Svelte project setup, making it ideal for isolated WordPress plugin components. First, ensure you have Node.js and npm (or yarn) installed. We’ll create a dedicated directory for our block and initialize a new Svelte project within it using a minimal template.

Navigate to your WordPress plugin directory (e.g., wp-content/plugins/) and create a new folder for your block plugin. Inside this folder, run the following commands to set up the Svelte project:

mkdir broken-link-checker-block
cd broken-link-checker-block
npm init -y
npm install --save-dev svelte rollup @rollup/plugin-node-resolve @rollup/plugin-commonjs rollup-plugin-css-only rollup-plugin-livereload rollup-plugin-svelte

Next, create a rollup.config.js file to configure the Svelte compilation process. This configuration will bundle our Svelte components into a single JavaScript file suitable for WordPress.

// rollup.config.js
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import css from 'rollup-plugin-css-only';
import livereload from 'rollup-plugin-livereload';
import svelte from 'rollup-plugin-svelte';

const production = !process.env.ROLLUP_WATCH;

export default {
	input: 'src/main.js', // Entry point for your Svelte application
	output: {
		file: '../broken-link-checker-block.js', // Output file for WordPress
		format: 'iife', // Immediately Invoked Function Expression
		name: 'brokenLinkCheckerBlock' // Global variable name
	},
	plugins: [
		svelte({
			compilerOptions: {
				// enable run-time checks when not in production
				dev: !production
			}
		}),
		// we'll extract any third-party CSS to this file
		css({ output: 'bundle.css' }),

		// If you're using any of the following options, make sure to install them
		// an install them.
		// If you have external dependencies installed from npm,
		// see https://github.com/rollup/rollup-plugin-commonjs
		commonjs(),

		// If you have setup a static server (like Express) to serve your Svelte app
		// then you can use this plugin to automatically reload the page when
		// the code is updated.
		// https://github.com/rixo/rollup-plugin-live-reload
		!production & livereload(),

		// If you wish to import Node.js modules and get them bundled in your
		// file, use this plugin.
		// https://github.com/rollup/rollup-plugin-node-resolve
		resolve({
			browser: true,
			dedupe: ['svelte']
		}),
	],
	watch: {
		clearScreen: false
	}
};

Create a src directory and inside it, a main.js file. This will be the entry point for our Svelte application. We’ll also create a App.svelte file for our main Svelte component.

// src/main.js
import App from './App.svelte';

const app = new App({
	target: document.body, // This will be adjusted for Gutenberg
	props: {
		name: 'world'
	}
});

export default app;

<!-- src/App.svelte -->
<script>
	export let name;
</script>

<h1>Hello {name}!</h1>

<style>
	h1 {
		color: purple;
	}
</style>

Finally, add a build script to your package.json:

{
  "name": "broken-link-checker-block",
  "version": "1.0.0",
  "description": "",
  "main": "src/main.js",
  "scripts": {
    "build": "rollup -c",
    "dev": "rollup -c -w"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@rollup/plugin-commonjs": "^25.0.7",
    "@rollup/plugin-node-resolve": "^15.2.3",
    "rollup": "^4.12.1",
    "rollup-plugin-css-only": "^1.0.0",
    "rollup-plugin-livereload": "^2.0.4",
    "rollup-plugin-svelte": "^7.7.2",
    "svelte": "^4.2.12"
  }
}

Run npm run dev to start the development server. This will watch for changes and recompile your Svelte code. You should see a broken-link-checker-block.js file generated in the root of your plugin directory.

Integrating Svelte with Gutenberg

Gutenberg blocks are registered using JavaScript. We need to adapt our Svelte output to work within the WordPress block editor. The key is to register a new block and then render our Svelte component within the block’s edit and save functions.

First, let’s modify our Svelte setup to output a component that can be mounted dynamically. We’ll remove the target: document.body from src/main.js and instead export a function that creates and mounts the Svelte component.

// src/main.js
import App from './App.svelte';

export function mountSvelteBlock(element, props = {}) {
	const app = new App({
		target: element,
		props: props
	});
	return app;
}

Now, create a PHP file for your WordPress plugin (e.g., broken-link-checker-block.php) and register the Gutenberg block. This PHP file will also enqueue the compiled Svelte JavaScript file.

<?php
/**
 * Plugin Name: Broken Link Checker Block
 * Description: A custom Gutenberg block to check for broken links.
 * Version: 1.0.0
 * Author: Your Name
 */

function broken_link_checker_block_register() {
    // Register the block
    register_block_type( __DIR__, array(
        'editor_script' => 'broken-link-checker-block-editor-script',
        'script'        => 'broken-link-checker-block-script',
        'render_callback' => 'broken_link_checker_block_render',
    ) );
}
add_action( 'init', 'broken_link_checker_block_register' );

function broken_link_checker_block_enqueue_scripts() {
    // Enqueue the compiled Svelte script for the editor
    wp_enqueue_script(
        'broken-link-checker-block-editor-script',
        plugins_url( 'broken-link-checker-block.js', __FILE__ ),
        array( 'wp-blocks', 'wp-element', 'wp-editor', 'wp-components', 'wp-i18n' ),
        filemtime( plugin_dir_path( __FILE__ ) . 'broken-link-checker-block.js' )
    );

    // Enqueue the compiled Svelte script for the frontend (if needed)
    wp_enqueue_script(
        'broken-link-checker-block-script',
        plugins_url( 'broken-link-checker-block.js', __FILE__ ),
        array(), // No dependencies for frontend script
        filemtime( plugin_dir_path( __FILE__ ) . 'broken-link-checker-block.js' )
    );
}
add_action( 'enqueue_block_editor_assets', 'broken_link_checker_block_enqueue_scripts' );

// Optional: Render callback for the frontend
function broken_link_checker_block_render( $attributes ) {
    // This function can return HTML to be rendered on the frontend.
    // For a dynamic block, you might fetch data here.
    // For this example, we'll assume the Svelte script handles frontend rendering.
    return '<div id="broken-link-checker-frontend"></div>';
}

The register_block_type function registers our block. The editor_script and script arguments point to the JavaScript file that will be enqueued. The render_callback is for server-side rendering, which we’ll skip for this client-side Svelte example, assuming the Svelte script will handle both editor and frontend rendering.

Building the Broken Link Checker Logic in Svelte

Now, let’s flesh out our App.svelte component to include the broken link checking functionality. We’ll need an input field for the URL, a button to trigger the check, and a display area for the results.

<!-- src/App.svelte -->
<script>
	import { createEventDispatcher } from 'svelte';

	const dispatch = createEventDispatcher();

	let urlToCheck = '';
	let results = [];
	let isLoading = false;
	let errorMessage = '';

	async function checkLinks() {
		if (!urlToCheck) {
			errorMessage = 'Please enter a URL.';
			return;
		}
		errorMessage = '';
		isLoading = true;
		results = [];

		try {
			// In a real-world scenario, you'd likely use a backend API
			// to perform the link checking to avoid CORS issues and
			// to handle more complex scraping.
			// For this example, we'll simulate a check.
			const response = await fetch('/wp-json/my-plugin/v1/check-links', {
				method: 'POST',
				headers: {
					'Content-Type': 'application/json',
				},
				body: JSON.stringify({ url: urlToCheck }),
			});

			if (!response.ok) {
				throw new Error(`HTTP error! status: ${response.status}`);
			}

			const data = await response.json();
			results = data.links || [];

		} catch (error) {
			errorMessage = `Error checking links: ${error.message}`;
			console.error('Link check failed:', error);
		} finally {
			isLoading = false;
		}
	}

	// Dispatch an event for Gutenberg's save function
	function saveBlock() {
		dispatch('save', { url: urlToCheck });
	}

	// For the editor, we need to mount the Svelte component
	// and handle its lifecycle.
	import { onMount, onDestroy } from 'svelte';

	onMount(() => {
		// If this is running in the editor, we need to hook into Gutenberg's
		// block saving mechanism.
		wp.data.subscribe(() => {
			const isSelected = wp.data.select('core/block-editor').isBlockSelected(wp.data.select('core/editor').getSelectedBlock());
			if (isSelected) {
				// This is a simplified approach. A more robust solution would
				// involve using the block's `setAttributes` function.
				// For now, we'll just dispatch a save event.
			}
		});
	});

	// We need to handle the initial attributes if the block is being edited
	// and has saved attributes.
	export let attributes = {};
	$: if (attributes.url) {
		urlToCheck = attributes.url;
	}

</script>

<div class="broken-link-checker-block">
	<h3>Broken Link Checker</h3>
	<div class="input-group">
		<input
			type="url"
			bind:value={urlToCheck}
			placeholder="Enter URL to check"
			disabled={isLoading}
		/>
		<button on:click={checkLinks} disabled={isLoading || !urlToCheck}>
			{isLoading ? 'Checking...' : 'Check Links'}
		</button>
	</div>
	{#if errorMessage}
		<p class="error-message">{errorMessage}</p>
	{/if}
	{#if results.length > 0}
		<h4>Results:</h4>
		<ul>
			{#each results as result (result.url)}
				<li class="{result.status === 'broken' ? 'broken' : ''}">
					<a href={result.url} target="_blank" rel="noopener noreferrer">{result.url}</a>
					- Status: {result.status} {result.status === 'broken' ? '(404)' : ''}
				</li>
			{/each}
		</ul>
	{:else if !isLoading && urlToCheck}
		<p>No broken links found (or check failed).</p>
	{/if}
</div>

<style>
	.broken-link-checker-block {
		border: 1px solid #ccc;
		padding: 15px;
		margin-bottom: 20px;
	}
	.input-group {
		display: flex;
		gap: 10px;
		margin-bottom: 15px;
	}
	.input-group input {
		flex-grow: 1;
		padding: 8px;
	}
	.input-group button {
		padding: 8px 15px;
		cursor: pointer;
	}
	.error-message {
		color: red;
		font-weight: bold;
	}
	ul {
		list-style: none;
		padding: 0;
	}
	li {
		margin-bottom: 5px;
	}
	li.broken {
		color: red;
		font-weight: bold;
	}
</style>

In this Svelte component:

  • We use bind:value to create a two-way binding for the URL input.
  • The checkLinks function simulates an API call to a WordPress REST API endpoint (which we’ll define next).
  • We use Svelte’s conditional rendering (`{#if}`) to show loading states, error messages, and results.
  • The createEventDispatcher and dispatch('save', ...) are crucial for integrating with Gutenberg’s attribute saving mechanism.
  • We export an attributes prop, which Gutenberg will use to pass saved block attributes. We use a reactive declaration (`$: if (attributes.url)`) to update the local state when attributes change.

Implementing the WordPress REST API Endpoint

To avoid CORS issues and to have a secure place to perform the link checking, we’ll create a custom WordPress REST API endpoint. This endpoint will receive the URL, perform the check (potentially using a server-side library), and return the results.

<?php
/**
 * Plugin Name: Broken Link Checker Block
 * Description: A custom Gutenberg block to check for broken links.
 * Version: 1.0.0
 * Author: Your Name
 */

// ... (previous code for register_block_type and enqueue_scripts) ...

// Add REST API endpoint for link checking
add_action( 'rest_api_init', function () {
    register_rest_route( 'my-plugin/v1', '/check-links', array(
        'methods' => 'POST',
        'callback' => 'my_plugin_check_links_callback',
        'permission_callback' => '__return_true', // For simplicity, allow anyone. In production, add proper authentication.
    ) );
} );

function my_plugin_check_links_callback( WP_REST_Request $request ) {
    $url = $request->get_json_params()['url'] ?? '';

    if ( empty( $url ) ) {
        return new WP_Error( 'invalid_url', 'URL is required.', array( 'status' => 400 ) );
    }

    // Basic URL validation
    if ( ! filter_var( $url, FILTER_VALIDATE_URL ) ) {
        return new WP_Error( 'invalid_url', 'Invalid URL format.', array( 'status' => 400 ) );
    }

    // In a real-world scenario, you would use a robust HTTP client and parsing library
    // to crawl the page and check links. For this example, we'll simulate the process.
    // You might use libraries like Guzzle or even simple cURL.

    // Simulate checking links
    $simulated_links = array();
    // Add some dummy links for demonstration
    $simulated_links[] = array( 'url' => $url . '/page1', 'status' => 'ok' );
    $simulated_links[] = array( 'url' => $url . '/broken-page', 'status' => 'broken' );
    $simulated_links[] = array( 'url' => $url . '/another-page', 'status' => 'ok' );

    // In a real implementation, you'd fetch the content of $url, parse it for links,
    // and then make HEAD or GET requests to each found link to check their status.
    // Example using cURL (simplified):
    /*
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_MAXREDIRS, 5);
    $content = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($http_code >= 400) {
        // Handle error, maybe return a specific error status for the main URL
    }

    // Use DOMDocument to parse HTML and find links
    $dom = new DOMDocument;
    @$dom->loadHTML($content); // Suppress warnings for malformed HTML

    $links = $dom->getElementsByTagName('a');
    $found_links = [];
    foreach ($links as $link) {
        $href = $link->getAttribute('href');
        if (filter_var($href, FILTER_VALIDATE_URL)) {
            // Make HEAD request to $href to check status
            $link_status = check_single_link_status($href); // Implement this function
            $found_links[] = ['url' => $href, 'status' => $link_status];
        }
    }
    */

    // For this example, we return simulated data
    $response_data = array(
        'message' => 'Link check initiated.',
        'links' => $simulated_links,
    );

    return new WP_REST_Response( $response_data, 200 );
}

// Helper function to check a single link (example)
function check_single_link_status($link_url) {
    // Implement actual HTTP request here (e.g., using cURL)
    // Return 'ok' or 'broken'
    // For simulation:
    return (strpos($link_url, 'broken') !== false) ? 'broken' : 'ok';
}

// Ensure the Svelte script is enqueued correctly in the PHP file
function broken_link_checker_block_enqueue_scripts() {
    wp_enqueue_script(
        'broken-link-checker-block-editor-script',
        plugins_url( 'broken-link-checker-block.js', __FILE__ ),
        array( 'wp-blocks', 'wp-element', 'wp-editor', 'wp-components', 'wp-i18n', 'wp-data' ), // Added 'wp-data' for Gutenberg API access
        filemtime( plugin_dir_path( __FILE__ ) . 'broken-link-checker-block.js' )
    );
}
add_action( 'enqueue_block_editor_assets', 'broken_link_checker_block_enqueue_scripts' );

// Register the block type
function broken_link_checker_block_register() {
    register_block_type( __DIR__, array(
        'editor_script' => 'broken-link-checker-block-editor-script',
        'attributes' => array(
            'url' => array(
                'type' => 'string',
                'default' => '',
            ),
        ),
        // No 'render_callback' needed if Svelte handles frontend rendering
    ) );
}
add_action( 'init', 'broken_link_checker_block_register' );

In the PHP code:

  • We hook into rest_api_init to register our custom route /my-plugin/v1/check-links.
  • The my_plugin_check_links_callback function handles the POST request, extracts the URL, performs basic validation, and returns simulated link check results.
  • Important: For production, you would replace the simulation with actual HTTP requests to check link statuses. Consider using a robust HTTP client library and potentially a background processing system for intensive checks.
  • We’ve also added an attributes definition to register_block_type to define the url attribute, which will be used to save the checked URL.

Connecting Svelte to Gutenberg’s Editor and Saving Attributes

The final piece is to ensure our Svelte component correctly interacts with Gutenberg’s block editor API. This involves rendering the Svelte component within the block’s edit function and saving its state as block attributes.

We need to modify our src/main.js to export a function that Gutenberg can use to render the block. This function will receive the block’s attributes and a function to update them.

// src/main.js
import App from './App.svelte';
import { mountSvelteBlock } from './mountSvelteBlock'; // Assuming mountSvelteBlock is in a separate file

// This function will be called by Gutenberg to render the block in the editor
export function Editor( { attributes, setAttributes } ) {
    let svelteApp = null;

    // Mount the Svelte component when the component mounts
    onMount(() => {
        const element = document.createElement('div');
        // We need a container element for Svelte to mount into.
        // Gutenberg's `edit` function doesn't directly provide a target element.
        // A common pattern is to create a temporary element and append it.
        // However, a more integrated approach is to use `wp.element.createElement`
        // and render the Svelte component within that.

        // Let's refine this: Gutenberg's `edit` function expects a React/WP Element.
        // We need to bridge Svelte to this. A common way is to use a wrapper
        // component or a direct mounting strategy.

        // For simplicity, let's assume we are rendering into a specific div
        // that Gutenberg provides or we create.
        // A better approach for complex Svelte integration might involve
        // a wrapper component that handles the Svelte lifecycle.

        // Let's try a direct mounting approach within the edit function's return.
        // The `edit` function should return JSX/WP Element.
        // We'll need a way to pass `setAttributes` to Svelte.

        // Re-thinking: The `edit` function in `register_block_type` expects a function
        // that returns WP Element. We can't directly return a Svelte component.
        // We need a wrapper.

        // Let's adjust the PHP to use a different registration approach if needed,
        // or create a JS wrapper.

        // Alternative: Use `wp.element.render` with a Svelte component.
        // This requires a container element.

        // Let's assume `App.svelte` is modified to accept `setAttributes`
        // and `attributes` as props.
        // The `save` function will be handled separately.
    });

    // The `edit` function should return WP Element.
    // We need to render our Svelte component within this.
    // This is where it gets tricky with Svelte standalone.

    // Let's simplify the Svelte component to accept attributes and a callback for saving.
    // And then use `wp.element.createElement` to render a placeholder,
    // and then mount Svelte into it.

    // This is a common challenge: integrating a framework like Svelte into React-based Gutenberg.
    // A robust solution often involves a JS wrapper that acts as a bridge.

    // Let's assume `App.svelte` is updated to handle `attributes` and `setAttributes`
    // and we will mount it into a div.

    // The `edit` function in `register_block_type` needs to return a WP Element.
    // We can create a div and then mount our Svelte app into it.

    // Let's create a dedicated Svelte wrapper component in JS.
    return wp.element.createElement(
        'div',
        {
            ref: (element) => {
                if (element && !svelteApp) {
                    svelteApp = mountSvelteBlock(element, {
                        attributes: attributes,
                        // Pass a function to update attributes
                        onSave: (newAttributes) => {
                            setAttributes(newAttributes);
                        }
                    });
                }
            }
        }
    );
}

// This function will be called by Gutenberg to save the block's content
export function Save( { attributes } ) {
    // The save function should return the markup to be saved in post content.
    // For a dynamic block, this might be empty or a placeholder.
    // For a static block, it should return the HTML representation.
    // Since our Svelte component handles rendering, we can return a simple div
    // that the frontend script will hydrate.
    return wp.element.createElement(
        'div',
        { className: 'broken-link-checker-frontend-wrapper', 'data-url': attributes.url },
        attributes.url ? `Checking links for: ${attributes.url}` : 'Broken Link Checker Block'
    );
}

// Update src/App.svelte to accept and use onSave prop
// Add this to src/App.svelte:
/*

*/

// Update src/mountSvelteBlock.js (create this file)
/*
// src/mountSvelteBlock.js
import App from './App.svelte';

export function mountSvelteBlock(element, props = {}) {
	const app = new App({
		target: element,
		props: props
	});
	return app;
}
*/

And update your src/App.svelte to accept and use the onSave prop:

<!-- src/App.svelte -->
<script>
	// ... existing imports and variables ...

	export let attributes = {}; // Props from Gutenberg
	export let onSave = () => {}; // Callback to save attributes

	let urlToCheck = '';

	// Initialize urlToCheck from attributes when the component mounts or attributes change
	$: urlToCheck = attributes.url || '';

	// Watch for changes in urlToCheck and dispatch the save event
	$: {
		if (urlToCheck !== attributes.url) {
			onSave({ url: urlToCheck });
		}
	}

	async function checkLinks() {
		// ... existing checkLinks logic ...
		// When results are obtained, update urlToCheck if needed,
		// but the primary saving mechanism is the reactive statement above.
	}

	// ... rest of your Svelte component ...
</script>

<!-- ... rest of your Svelte template ... -->

In the PHP file, we need to adjust the register_block_type call to include the edit and save functions:

// broken-link-checker-block.php
// ... (other parts of the file) ...

function broken_link_checker_block_register() {
    register_block_type( __DIR__, array(
        'editor_script' => 'broken-link-checker-block-editor-script',
        'attributes' => array(
            'url' => array(
                'type' => 'string',
                'default' => '',
            ),
        ),
        // Define editor and save functions
        'editor_script' => 'broken-link-checker-block-editor-script',
        'editor_style'  => null, // Optional: enqueue editor-specific CSS
        'script'        => 'broken-link-checker-block-script', // Frontend script
        'style'         => null, // Optional: enqueue frontend CSS
    ) );
}
add_action( 'init', 'broken_link_checker_block_register' );

// Enqueue scripts for the editor
function broken_link_checker_block_enqueue_scripts() {
    wp_enqueue_script(
        'broken-link-checker-block-editor-script',
        plugins_url( 'broken-link-checker-block.js', __FILE__ ),
        array( 'wp-blocks', 'wp-element', 'wp-editor', 'wp-components', 'wp-i18n', 'wp-data' ),
        filemtime( plugin_dir_path( __FILE__ ) . 'broken-link-checker-block.js' )
    );

    // Make block attributes and settings available to JavaScript
    wp_localize_script( 'broken-link-checker-block-editor-script', 'blockSettings', array(
        'attributes' => array(
            'url' => '', // Default value
        ),
    ) );
}
add_action( 'enqueue_block_editor_assets', 'broken_link_checker_block_enqueue_scripts' );

// We need to export the edit and save functions from our JS file.
// Let's assume `broken-link-checker-block.js` now exports `Editor` and `Save`.
// The `register_block_type` function in PHP doesn't directly take JS functions.
// Instead, we use `wp.blocks.registerBlockType` in our JavaScript.

// Let's revise the JS registration part.
// The PHP `register_block_type` is for server-side registration.
// For client-side blocks, we use `wp.blocks.registerBlockType` in JS.

// Revised approach: Remove `register_block_type` from PHP and handle registration entirely in JS.
// The PHP file will only enqueue the script.

Revised JavaScript Registration (src/main.js):

// src/main.js
import { registerBlockType } from '@wordpress/blocks';
import { Editor } from './Editor'; // Assuming Editor.js exports the edit component
import { Save } from './Save';     // Assuming Save.js exports the save component
import './style.scss'; // If you have SCSS for styling

registerBlockType( 'my-plugin/broken-link-checker', {
    title: 'Broken Link Checker',
    icon: '

Recent Posts

Top Categories

Our Products

Our Services