The Beginner’s Guide to Developing a Custom WordPress Theme With Flynt

Flynt is a WordPress starter theme, like underscores or Sage. It’s meant to be customized at core level, not to be installed and maintained as a parent theme. What’s unique about Flynt, is the component based architecture, powered by Advanced Custom Fields Pro (ACF Pro) and Timber.

In Flynt, almost anything is a component. Most components are flexible content layouts, which can be added dynamically to a page. Other components are statically added to a template, like the main navigation, or the blog post header.

1. Install WordPress & ACF Pro

Flynt is a theme only and does not come with a project structure. Use a WordPress boilerplate like Bedrock, or set up a standard installation of the latest WordPress version on your development environment. It’s important that your development setup supports running node and composer.

Configure a local domain host for your WordPress installation and run the WordPress installation process. We’ll assume you set your local domain host to my-project.test.

Install the ACF Pro plugin, which is a requirement due to its flexible content field, which allows to dynamically add components to a page.

2. Download and configure Flynt

Download the latest version of the Flynt theme, or generate a new repository based on Flynt, by clicking Use this template in the original Flynt repository.

Move the theme to /wp-content/themes and change the directory name to your project name. It does not need to be “flynt”. You may also change the theme name and any information in the style.css, as well as the screenshot.png. We’ll assume you renamed the theme directory to my-project.

Change the host variable in my-project/build-config.js to match your host URL: const host = 'my-project.test'.

Install the composer and node dependencies and run the build process once, by entering the following commands in your console:

# wp-content/themes/my-project
composer install
npm install
npm run build

Activate the theme in the WordPress backend.

Go to Pages and click to edit the Front Page. In the bottom right corner, click the Add Component button to add your first component. Fill the component with sample content and click Preview Changes to see the result.

You’ve successfully installed, configured and built the Flynt starter theme. Time to get started with development!

3. Run the file watcher

The command npm run build bundles and optimizes assets for production use. Run the command before deploying your theme to a production environment.

For the development workflow, it’s much more convenient to run the browser sync file watcher. Browser sync continuously compiles .scss files to .css, and .js files with babel. Each time you save a .scss or .js file, your browser will update with the changes made.

To run the file watcher and browser sync, enter the following command in your console:

# wp-content/themes/my-project
npm start

Browser sync will start a local server on localhost:3000 and proxy it to the host you’ve configured in the build-config.js in step 2. It’s important that your website is available under the given domain host for browser sync to work.

Go to localhost:3000 and change a .scss file in your theme. Your browser should update with the change made almost instantly. If the browser doesn’t update, check your console for errors.

4. Customize the BaseStyle

Each component has a .scss file that defines its unique style. Component styles are scoped to the component container by convention, to avoid style changes affecting other components. However, some generic styles need to be defined globally to ensure a consistent appearance across components. In Flynt, all those global elements and styles are collected in what’s called the Base Style.

Navigate your browser to localhost:3000/BaseStyle/ to view the Base Style template from my-project/​templates/basestyle.twig. Adjust the styles in your theme file my-project/​assets/styles/_base.scss according to your custom design needs.

5. Modify existing components

To get familiar with the component concept, check out and play around with some components in the components folder my-project/Components/. Pick an easy one to start with, like BlockImage. Modify the markup in index.twig and styles.scss to your liking, and watch the changes enfold in the browser.

Next, investigate the script.js of the SliderImages to understand how custom elements are utilized to initialize component scripts, and how adding JavaScript dependencies works.

On the server side, try adding new fields to the backend in the component’s functions.php. The Flynt VS Code Snippets will help with the ACF field syntax. And finally, discover the possibilities of processing data before it’s handed to the template, via Flynt filters by the example of GridPostsLatest.

6. Create custom components

The Flynt Base Components and Premium Components give you a head start for your projects, but they’re not meant to be complete. Achieve more variety and get more creative with developing your own custom components. Either start from scratch with the Flynt Yeoman Generator, or duplicate existing components that come close to your needs.

If you want your component to appear in the Add Component button list, add the field layouts to my-project/inc/​fieldGroups/pageComponents.php. If you want to render a component statically to a template, use the Twig function renderComponent('BlockMyComponent').

Welcome on board!

You’re now working component based in WordPress. You’ve seen the most important parts and are ready to build any custom theme based on Flynt.

Going ahead, you might want to learn more about working with Timber, how to create custom post types, and which other customizations Flynt comes with. And once your custom theme is done, consider setting up a continuous deployment pipeline using GitHub actions to ship your code to production.