Installation

This chapter walks your team through installing CivicTheme on a standalone Drupal site. By the end, you will have CivicTheme installed via Composer, required modules enabled, a sub-theme generated, front-end assets built, and the site ready for customisation.

Unlike GovCMS SaaS, a standard Drupal site uses Composer to manage theme dependencies, which simplifies the installation process.

Prerequisites

• A working Drupal 10.2+ or 11+ site with Composer-managed dependencies

• Composer installed and available on the command line

• Drush installed (recommended for command-line operations)

• NodeJS 22+ and NPM 10+ available on your machine

• Administrator access to the Drupal site

Step 1: Install CivicTheme and enable modules

For instructions on installing CivicTheme via Composer, see the Drupal theme installation reference.

Step 2: Generate your sub-theme

CivicTheme must not be modified directly — all custom work happens in a sub-theme. A script generates the full sub-theme scaffold:

cd web/themes/contrib/civictheme
php civictheme_create_subtheme.php <SUBTHEME_MACHINE_NAME> "<Subtheme Human Name>" "<A description>" ../custom/<SUBTHEME_MACHINE_NAME> --remove-examples

Then enable it:

drush theme:enable <SUBTHEME_MACHINE_NAME> -y
drush config-set -y system.theme default <SUBTHEME_MACHINE_NAME>

Naming tip: Name your sub-theme after the site, not after CivicTheme. Avoid including "civic" or "civictheme" in the machine name — it creates confusion when maintaining the theme later.

The script options and the generated directory structure are documented in the sub-theme reference.

Step 3: Build front-end assets

cd web/themes/custom/<SUBTHEME_MACHINE_NAME>
nvm use
npm install
npm run build

Verify that the dist directory was created. Navigate to your site in the browser and confirm that default CivicTheme styling is applied.

Commit built assets

The generated sub-theme ignores the compiled dist/ directory by default. Unless your deployment pipeline runs npm run build, the deployed site needs the built assets committed to the repository — otherwise it loads with no CivicTheme styling.

1. Edit the .gitignore in your sub-theme and remove the dist line.

2. Add the build's temporary directories so they are not committed:

   .components-civictheme
   components_combined
   node_modules

3. Run npm run build and commit the contents of dist/.

For the full explanation and the build-during-deployment alternative, see Committing built assets.

Step 4: Provision content

CivicTheme includes pre-configured blocks, menus, and configuration entities that set up the default site structure.

Navigate to /admin/appearance/settings/<SUBTHEME_MACHINE_NAME> and press the Provision content button. Then export configuration with drush cex -y.

See the Provision content section for more information.

Step 5: Verify the installation

After provisioning, your site should match the default CivicTheme site (without homepage content). Check that:

• The header displays with the CivicTheme logo and navigation

• The footer displays with default blocks (social links, footer navigation, acknowledgement, copyright)

• The site responds correctly on mobile (navigation collapses to mobile menu)

• The admin theme is accessible at /admin

Troubleshooting

For common installation issues (content not appearing, styling not applied, module dependency errors), see the troubleshooting section in the Drupal theme installation reference.

Where to get help

For all support options, see Getting help.

Next step

With CivicTheme installed and your sub-theme generated, the next step is to understand the sub-theme structure and set up your local development workflow.

Continue to Chapter 2: Setting Up Your Sub-Theme.