4wp.dev – FSE WordPress development

Step 1: Basic Theme Structure – FSE Theme Development

—

by

Anatoliy Dovgun

Step 1: Basic Theme Structure

Create the fundamental folder structure for a Full Site Editor (FSE) theme following WordPress best practices.

Code Snippet:

cd wp-content/themes/4wp-starter-theme
mkdir -p {assets/{css,js,images},inc,parts,patterns,styles,templates}

What This Creates:

  • assets/ – Static files (CSS, JS, images)
  • inc/ – PHP includes and functions
  • parts/ – Template parts (header, footer, etc.)
  • patterns/ – Block patterns
  • styles/ – Theme style variations
  • templates/ – HTML template files

Complete File Creation with Git Workflow (Recommended):

Note: Using Git for version control is highly recommended for professional WordPress development. This workflow demonstrates best practices for semantic versioning and project management.

# Create main theme files
cat > style.css << 'EOF'
/*
Theme Name: 4WP Starter Theme
Description: Full Site Editing starter theme built for developers
Version: 1.0.0
Text Domain: fourwp-starter
*/
EOF

cat > theme.json << 'EOF'
{
	"version": 3,
	"settings": {
		"appearanceTools": true,
		"layout": {
			"contentSize": "840px",
			"wideSize": "1200px"
		}
	}
}
EOF

cat > functions.php << 'EOF'
<?php
/**
 * 4WP Starter Theme Functions
 */

// Prevent direct access
if (!defined('ABSPATH')) {
    exit;
}

// Theme setup
function fourwp_theme_setup() {
    add_theme_support('post-thumbnails');
    add_theme_support('title-tag');
    add_theme_support('custom-logo');
}
add_action('after_setup_theme', 'fourwp_theme_setup');
EOF

# Create .gitkeep files
echo "# Placeholder for CSS files" > assets/css/.gitkeep
echo "# Placeholder for JS files" > assets/js/.gitkeep
echo "# Placeholder for images" > assets/images/.gitkeep
echo "# Placeholder for includes" > inc/.gitkeep
echo "# Placeholder for patterns" > patterns/.gitkeep
echo "# Placeholder for styles" > styles/.gitkeep

# Git workflow with semantic versioning
git add .
git commit -m "feat: add basic FSE theme structure

- Add style.css with theme header v1.0.0
- Add theme.json with basic settings
- Add functions.php with theme setup
- Add directory structure with .gitkeep files

Completes Step 1 of FSE theme development"

git tag -a v1.0.0 -m "Release v1.0.0: Basic FSE Theme Structure"
git push origin main --tags

Why .gitkeep Files?

Git doesn’t track empty directories – only files. The .gitkeep files ensure our FSE theme structure is preserved in version control.

Next Step:

After creating the structure, we’ll add the essential theme files (style.css, theme.json, functions.php).

Resources & References

FAQ for

Step 1: Basic Theme Structure – FSE Theme Development

Basic Questions:

  • Can I change architecture after theme creation?

  • Which files are required for FSE theme?

  • Why proper architecture matters in WordPress themes?

  • What is FSE theme and how it differs from classic theme?

Technical Questions:

  • How to organize files via command line?

  • What are .gitkeep files and why do we need them?

  • Is template-parts/ directory mandatory?

  • Why patterns/ directory needed in FSE theme?

  • What goes in assets/ vs inc/ directory?

Practical Questions:

  • Where to store custom CSS and JavaScript?

  • Which files to add after directory setup?

  • How to verify theme architecture correctness?

  • Where to start FSE theme development?

Methodology Questions:

  • How to prepare testing environment for FSE?

    Setting up a proper FSE testing environment begins with installing a fresh WordPress instance using the latest version to ensure compatibility with current FSE features. Use local development tools like Local by Flywheel, XAMPP, or Docker to create an isolated environment that mirrors your production server configuration. Enable WordPress debugging by setting WP_DEBUG to true in wp-config.php to catch any theme-related errors during development.

    Install essential testing plugins including Theme Check for WordPress standards validation, Query Monitor for performance debugging, and Health Check for identifying plugin conflicts. Create multiple user roles to test FSE functionality across different permission levels, ensuring that editors and contributors can properly interact with your theme’s templates and patterns. Set up sample content that represents real-world usage scenarios, including posts, pages, and custom post types if your theme supports them.

    Configure your testing environment with various browsers and devices to verify cross-platform compatibility. Use browser developer tools to test responsive design and accessibility features built into your FSE theme. Establish a staging site that replicates your production environment for final testing before deployment, and implement automated testing workflows using tools like Playwright or Cypress to ensure consistent theme behavior across different WordPress configurations and block editor scenarios.

  • Which tools to use for FSE development?

    The essential toolkit for FSE development starts with a modern code editor like Visual Studio Code equipped with WordPress-specific extensions such as WordPress Snippets and PHP Intelephense. Local development environments like Local by Flywheel, XAMPP, or Docker-based solutions provide the necessary WordPress installation for testing FSE themes. The WordPress Site Editor itself serves as the primary visual development tool for creating and editing templates, patterns, and template parts.

    Version control systems, particularly Git with platforms like GitHub or GitLab, are crucial for collaborative FSE development and theme versioning. Build tools such as Webpack, Gulp, or Vite help optimize CSS and JavaScript assets, while SASS or PostCSS processors enhance styling workflows. Browser developer tools become indispensable for debugging block-specific CSS and inspecting the complex HTML structure generated by Gutenberg blocks.

    Specialized WordPress development tools include WP-CLI for command-line operations, Query Monitor for debugging, and Theme Check plugin for validation against WordPress standards. JSON validators ensure proper theme.json syntax, while accessibility testing tools like axe DevTools help maintain WCAG compliance. Design tools like Figma or Sketch facilitate pattern design and layout planning before implementation in the block editor environment.

  • How to organize team work on FSE theme?

    Organizing team work on FSE themes requires establishing clear file ownership and workflow protocols. Begin by dividing responsibilities based on the FSE theme structure: assign template developers to focus on the templates directory, pattern creators to work on the patterns folder, and styling specialists to manage theme.json and CSS files. This separation prevents conflicts and allows team members to work simultaneously on different components.

    Implement version control best practices using Git with feature branches for each theme component. Create separate branches for templates, patterns, template-parts, and styling changes. Establish naming conventions for commits that clearly identify which FSE component is being modified, such as “template: add single-post layout” or “pattern: create hero section”. This approach ensures smooth merging and easier conflict resolution when multiple developers work on interconnected theme elements.

    Set up development environments that mirror production WordPress installations with identical block editor configurations. Use staging sites for testing theme changes before deployment, and establish code review processes specifically for FSE components. Regular team synchronization meetings should focus on pattern consistency, template compatibility, and overall theme cohesion to maintain design integrity across all team contributions.

  • What international FSE standards exist?

    Full Site Editing follows WordPress’s own coding standards and guidelines rather than separate international standards. The primary framework is the WordPress Theme Review Guidelines, which serve as the de facto international standard for FSE theme development across the global WordPress community.

    The WordPress coding standards encompass PHP, HTML, CSS, and JavaScript standards that align with widely accepted web development practices. These include PSR coding standards for PHP, W3C guidelines for HTML and CSS, and ECMAScript standards for JavaScript. Additionally, FSE themes must comply with WordPress accessibility standards, which follow WCAG guidelines for international web accessibility.

    Theme.json schema serves as another standardization layer, providing a consistent API for theme configuration across all FSE themes globally. This JSON-based approach ensures that themes maintain compatibility and consistency regardless of their origin or target market. The WordPress Core team continuously updates these standards to reflect evolving web technologies and international best practices in theme development.