Published November 27, 2023

I do a lot of work with 11ty and I love it. It's a great static site generator that's simple to use and has a lot of flexibility. Recently I discovered Visual Studio Code Tasks and I'm using them to automatically start the 11ty server when I open a project and to fix one real annoyance with 11ty's dev server: not updating when a WebC component changes that is used inside a layout.

The Problem #

I love WebC components. They're a great way to embrace vanilla HTML Web Components. I love them so much I use them all over my projects, including inside my layouts (which) are also .webc files. But, 11ty's dev server doesn't update correctly when a component used inside a layout changes. It's a known, but closed and unresolved, issue that's irked me for years with no workarounds. Until now.

Solving it with VS Code's tasks.json #

VS Code has a great feature called Tasks that lets you run commands from inside the editor. You can run them manually or you can configure them to run automatically when you open a project. I'm using them to run the 11ty server and to fix the problem with WebC components not updating.

Step one is to create a .vscode directory in your project. Inside that directory create a tasks.json file. This is where we'll configure our tasks. Each task has lots of options that you can learn about in the docs, but I'm going to give you the ones I use.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build and Watch Assets",
      "type": "shell",
      "command": "npm run dev",
      "group": "build",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      },
      "runOptions": {
        "runOn": "folderOpen"
      },
      "problemMatcher": []
    },
    {
      "label": "Run 11ty server",
      "type": "shell",
      "command": "npx @11ty/eleventy --serve --incremental",
      "group": "build",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      },
      "runOptions": {
        "runOn": "folderOpen"
      },
      "problemMatcher": []
    },
    {
      "label": "Update 11ty layouts when components change",
      "type": "shell",
      "command": "npx --yes nodemon --watch _components/ --ext webc --exec find _layouts/ -name '*.webc' -exec touch {} +",
      "group": "build",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      },
      "runOptions": {
        "runOn": "folderOpen"
      },
      "problemMatcher": []
    }
  ]
}

I've got three tasks here. The first runs an npm script that builds my assets. Feel free to remove or repurpose that for your own needs. The second runs the 11ty server in incremental mode. The third is the magic that fixes the problem with WebC components not updating. Let's break down that command:

npx --yes nodemon --watch _components/ --ext webc --exec find _layouts/ -name '*.webc' -exec touch {} +

The first part, npx --yes nodemon, runs nodemon, a tool that watches files and runs a command when they change. (The --yes flag tells it to always answer "yes" to any prompts.) The next part, --watch _components/ --ext webc, tells nodemon to watch the _components directory for changes to files with the .webc. If you're using a different directory for your components, change that part of the command to match. The last part, --exec find _layouts/ -name '*.webc' -exec touch {} +, tells nodemon to run the find command when a component changes. The find command finds all the .webc files in the _layouts directory (again, change that to suit your project's layout) and runs touch on them. This updates the timestamp on the files, which tells 11ty to rebuild them. That's the trick. By forcing an update to the layout files, 11ty rebuilds them and the changes to the components are picked up.

Running the tasks #

Now that we've got our tasks configured, we need to run them. You can run them manually by opening the command palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows) and searching for "Run Task". You'll see a list of all the tasks you've configured. Select the one you want to run and it will run in a new terminal window. This configuration is also set to run whenever this project is opened. Nothing else needed.

I hope 11ty fixes this issue at some point, but until then, this is a great workaround.