Eleventy uses the
debug package to log
debug messages to the console. If something is going wrong with your
build, you can set the
DEBUG environment variable to view
log messages from specific parts of Eleventy, or all of it. The
Eleventy docs refer to this as
debug is already installed with your Eleventy
project, you might want to take advantage of it yourself to debug your
own code. All you have to do is import the
and create a logger with your namespace. For example, suppose you have
some computed data that pulls data from a database.
Now if we need to debug our database fetch, we can run our build with
DEBUG=darthmall:database in the environment.
There’s just one problem with the above solution: when we set
DEBUG=darthmall:database, all of the output from Eleventy
disappears. If you’re trying to debug some part of your site locally,
this is great because it keeps unrelated log messages out of sight.
But what if you want these logs included as part of a build—say in
CI—so that if a build fails you can go back and see the
reason. In this case, you may want to add your logs to the default
Eleventy output so that the logs in CI are more informative.
If you dig around in the
Eleventy source code, you’ll find that the default Eleventy messages are output to the
Eleventy:Logger namespace. We can add this to our
DEBUG environment variable with a comma and then both of
the default Eleventy log messages and our database log messages will
Et voilà! We get to see Eleventy’s usual output about writing templates and so on along with the output from our database code. This way we get nice status messages in our builds, but if something goes wrong, we don’t have to re-run the build in CI to find out what went wrong.
If you happen to be buiding your Eleventy site with GitLab CI, you
have to be careful about how you set your
You might be tempted—as I was—to set it as a variable in the job.
Doing this will probably break your builds. For some reason, setting a
DEBUG variable in the job like this, causes artifact
uploads to fail as well as some other bad behaviors. There’s an
open issue for GitLab CI, which has been open for several years. Instead, you should set the
DEBUG variable when you invoke
This limits the scope of the
DEBUG environment variable
to just your Eleventy build process, so that when it comes time for
GitLab to upload artifacts or do any other work, the variable is not
present and everything continues to function normally.