Written by: Geoffrey Callaghan

how to create a gridsome theme

How To Create A Gridsome Theme

Creating a Gridsome theme involves setting up a collection of reusable components, layouts, styles, and configurations that can be easily applied to multiple Gridsome projects. Gridsome, like other modern static site generators, allows for flexible theming using Vue.js components, GraphQL for data fetching, and CSS for styling. Here’s a step-by-step guide to help you create a Gridsome theme:

Step 1: Set Up Your Environment

  1. Install Node.js and npm: Ensure you have Node.js and npm (or Yarn) installed. You can download and install from nodejs.org.

  2. Install Gridsome CLI: Install the Gridsome CLI globally.

    npm install -g @gridsome/cli

Step 2: Create a New Gridsome Project

  1. Initialize a New Gridsome Project: Use the Gridsome CLI to create a new project.

    gridsome create my-gridsome-site
    cd my-gridsome-site
  2. Explore the Project Structure: Familiarize yourself with the Gridsome project structure. Key directories include src (where your Vue components and GraphQL queries reside), static (for static assets), and gridsome.config.js (Gridsome configuration).

Step 3: Set Up Your Gridsome Theme

  1. Create a New Theme Directory: Inside the src directory of your Gridsome project, create a directory for your theme.

    cd src
    mkdir themes
    cd themes
    mkdir my-theme
    cd my-theme
  2. Initialize a package.json for Your Theme: Initialize your theme directory as an npm package.

    npm init -y

Step 4: Develop Theme Components

  1. Create Vue Components: Create reusable Vue components for your theme. Here’s an example of a Button component:

    <!-- src/themes/my-theme/components/Button.vue -->
      <button class="btn" @click="onClick">
    export default {
      props: {
        onClick: {
          type: Function,
          default: () => {}
    <style scoped>
    .btn {
      padding: 10px 20px;
      border: none;
      border-radius: 4px;
      background-color: #0070f3;
      color: white;
      cursor: pointer;
      transition: background-color 0.3s;
    .btn:hover {
      background-color: #005bb5;
  2. Create Layout Components: Layout components define the structure of your pages. Here’s a basic DefaultLayout example:

    <!-- src/themes/my-theme/layouts/DefaultLayout.vue -->
        <Header />
          <slot />
        <Footer />
    import Header from './Header.vue';
    import Footer from './Footer.vue';
    export default {
      components: {

Step 5: Configure Your Gridsome Theme

  1. Update Gridsome Configuration: Modify the gridsome.config.js file in your theme to configure any plugins or global settings specific to your theme.

    // src/themes/my-theme/gridsome.config.js
    module.exports = {
      // Configuration options
  2. Add Global CSS: Include a global CSS file for your theme.

    /* src/themes/my-theme/assets/style.css */
    body {
      font-family: Arial, sans-serif;
      line-height: 1.6;
      background-color: #f0f0f0;
    /* Add more global styles as needed */

Step 6: Using Your Gridsome Theme

  1. Apply Your Theme in a Gridsome Project: Use your theme components and layouts in a Gridsome project.

    <!-- src/pages/Index.vue -->
        <h1>Welcome to My Gridsome Site</h1>
        <Button @click="handleClick">Click Me</Button>
    import { Button, Layout } from '@/themes/my-theme/components';
    export default {
      components: {
      methods: {
        handleClick() {
          console.log('Button clicked!');

Step 7: Publish and Share Your Gridsome Theme

  1. Publish Your Theme (Optional): If you want to share your theme with others, publish it as an npm package or make it available in a public repository.

    cd src/themes/my-theme
    npm publish --access public

Final Steps

  1. Test Your Theme: Test your theme thoroughly in different scenarios to ensure it works as expected and is responsive.

  2. Document Your Theme: Provide clear documentation on how to install, use, and customize your Gridsome theme in a README.md file.

By following these steps, you can create a reusable Gridsome theme that includes components, layouts, and styles for consistent and efficient development of Gridsome projects.