Getting to know Eleventy 3 codebase

[Zearin]

@zachleat I’ve been trying to become familiar with the Eleventy codebase, and there are a number of things I’ve wondered about the code’s structure.

Since v3 is on the horizon, I thought I’d try and aggregate some questions, so the answers may hopefully benefit others as well.

Note: Also, I want to say I’m asking these questions with a great deal of respect and admiration for this fantastic project. In the past, sometimes my words were received as confrontational (in other contexts, not here). Invariably I was blind to the danger until after I’d offended someone. I try hard to avoid this, and I usually succeed. But I wanted to make sure I am clear that here I’m only interested in learning from a project I have loved for years. :)

• Errors. There is an Errors folder, but also several Error subclasses sprinkled throughout many files.
  • Why are Errors defined using two different practices? (Centralized vs. alongside code that throws them)
  • After all the specialized Error subclasses defined, there are many instances of throw new Error(...). Is this because they are less likely to occur?
• Template*.js files. The src/Template\*.js files outnumber even the src/Eleventy\*.js files. Is there a reason these aren’t grouped into a directory?
• Getters and Setters. There is a curious mix of getThing() and get thing() throughout. (And likewise for setters.) Is this just historical legacy from before getters and setters were supported syntax? Are there instances where you used the getThing() style because there would be a problem using a get thing()?
  • Example: In the TemplateWriter class, I even found the following snippet:

    setEleventyFiles(eleventyFiles) {
            this.eleventyFiles = eleventyFiles;
        }
    
    
        set eleventyFiles(eleventyFiles) {
            this._eleventyFiles = eleventyFiles;
        }
    

• Control Flow. Probably the most important question here: What is the control flow of the program?
  • I’m not talking about the Order of Operations page in the docs (although it is helpful!). I mean, how does execution pass from class to class during a typical build?

[Snapstromegon]

Hi @Zearin, nice to see someone trying to get familiar with the codebase and maybe even I can learn something from this issue.

I will try to respond to the best of my abilities:

• Errors that are meant to be thrown in different places are often in the Errors folder, while Errors thrown only at one location are in that location. At the same time errors that are more of an info to the user and also don't need to be a EleventyBaseError are often just a new Error() - especially when they are a one-off (at least that's how I understand it).
• It'd be possible to move Template* and Eleventy* files into separate folders, but I think this has just grown over time and isn't yet a real problem.
• Getters and setters are often grown historically or from a need for async support, which is nicer to write with getThing than with get thing.
• Good question - for me it's kind of a magic box that I started to look into step by step, so I know what I've touched, but my knowledge still has gaps. In general I think the naming is fairly okay, so if I know the concept I work on, I find the relevant files.

[uncenter]

I've also been trying to learn the code base and I have to say, the last part that you mentioned is the most confusing. I often find myself starting at the beginning of the CLI execution and I just trace my way through each of the classes and methods lol.

[Zearin]

Okay, I think I’d like to start another round of Q&A to get to know the codebase.

I want to try to identify all parts of the codebase that fulfill certain roles. I’ll start with Config in this post.

Config objects

• Config classes.
  • UserConfig and TemplateConfig (with defaultConfig providing, um, defaults) appear to be the only classes dedicated to configuration (according to their names).
• eleventyConfig.
  • Many class constructors and methods accept an eleventyConfig argument.
  • In Eleventy.initializeConfig(), this is a TemplateConfig instance.
  • A TemplateConfig instance holds a reference to a UserConfig instance. If I understand correctly, this is so that a user’s configuration can be tweaked on a template-by-template basis. Is this correct?
• “Config” vs. “options”.
  • When a class handles both “config” and “options”, what distinguishes whether a setting falls into one category or another?
• Total configuration awareness®.
  • Are there any other types of config?
  • What makes their roles different?
  • Which ones override others (and in which circumstances)?

[Zearin]

Files & Paths

According to filenames, below is a list of all the files/classes that deal with files or paths (including “globs”). I’ll list path-related dependencies outside of the node: standard library under each one.

I’m trying to get a list of all path-related functionality here. I’m not trying to include I/O (read/write) operations. If a class does some of both, and its name implies more path-related purpose, then I’ll include it.

• 📂 Util/
  • DirContains
  • PathNormalizer
    • uses TemplatePath from @11ty/eleventy-utils
  • PathPrefixer
    • uses PathNormalizer
• EleventyFiles
  • uses TemplateGlob
  • uses TemplatePath from @11ty/eleventy-utils
• FileSystemSearch
  • uses TemplatePath from @11ty/eleventy-utils
  • uses fastglob and micromatch (3rd party deps)
• TemplateFileSlug
  • uses TemplatePath from @11ty/eleventy-utils
• TemplateGlob
  • uses TemplatePath from @11ty/eleventy-utils

Here’s where you come in!

Did I miss anything?

Any observations about the above?

[Zearin]

Next entry: Class constructor signatures.

I created this gist with the signature of every constructor in Eleventy.

Do you notice any patterns?

[zachleat]

Are y’all okay if I move this to be a Discussion? Trying to separate out issues from discussion topics.

Thanks!