The Beginner’s Guide to Developing a Custom WordPress Theme With Flynt
First time Flynt user? This tutorial will walk you through a typical Flynt process. From setting up the theme, to the development workflow and creating custom components.

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.