@thegetty/quire-cli 1.0.0-pre-release.11 → 1.0.0-pre-release.13

package/src/lib/11ty/README.md

@@ -2,14 +2,34 @@
 
 The `quire-cli/lib/11ty` module is a façade for interacting with Eleventy, the static site generator for Quire projects.
 
+### 11ty/API module
+
+The `api` module allows the Quire CLI to programmatical configure an instance of Eleventy on which it can call methods.
+
+See [Eleventy Documentation: Programmatic API](https://www.11ty.dev/docs/programmatic/)
+
 ### 11ty/CLI module
 
 The `cli` module is a wrapper around the Eleventy CLI to run `@11ty/eleventy` commands.
 
 See [Eleventy Documentation: Command Line Usage](https://www.11ty.dev/docs/usage/#command-line-usage)
 
-### 11ty/Eleventy module
+### Paths module
 
-The `eleventy` module allows the Quire CLI to programmatical configure an instance of Eleventy on which it can call methods.
+The `paths` module returns paths for a Quire project to configure the Eleventy instance:
 
-See [Eleventy Documentation: Programmatic API](https://www.11ty.dev/docs/programmatic/)
+- _absolute_ path to the [Eleventy configuration](https://www.11ty.dev/docs/config/) file
+- _relative_ path *from* the `quire-11ty` source *to* the `input` and `output` directories for the project
+- _relative_ path *from* the project `input` *to* the Eleventy `includes` and `layouts` directories
+
+
+Set environment variables for paths relative to eleventy `input` dir,
+    * allowing a project agnostic `quire-11ty` eleventy configuration file.
+    * Nota bene: environment variables read into the eleventy configuration
+    * file _must_ be set before the eleventy configuration file is parsed.
+
+`Eleventy` does not expose an API to set the relative `includes` and `layouts` paths on the instance. In order to decouple the Eleventy configuration file from a specific project and its path on the system the exported `paths` are used by the `api` and `cli` modules to set environment variables that can be used in the `.eleventy.js` configuration.
+
+These environment variables **must be set before** the `Eleventy` instance is created and the `.eleventy.js` configuration is parsed.
+
+**Nota bene** The current implementation of the `Eleventy` `TemplatePathResolver` assumes that the `layouts` directory is a child of the `input` directory and prevents decoupling the Quire project content from the `quire-11ty` code; see [eleventy#2655](https://github.com/11ty/eleventy/issues/2655).

package/src/lib/11ty/api.js

@@ -35,6 +35,17 @@ const factory = async (options = {}) => {
     expand: true,
   }
 
+  /**
+   * Set environment variables for paths relative to eleventy `input` dir,
+   * to allow `quire-11ty` to be decouple from the project input directory.
+   * Nota bene: environment variables read into the eleventy configuration
+   * file _must_ be set before the eleventy configuration file is parsed.
+   * @see https://github.com/11ty/eleventy/issues/2655
+   */
+  process.env.ELEVENTY_DATA = paths.data
+  process.env.ELEVENTY_INCLUDES = paths.includes
+  process.env.ELEVENTY_LAYOUTS = paths.layouts
+
   /**
    * Get an instance of the runtime of eleventy.
    * @see https://github.com/11ty/eleventy/blob/src/Eleventy.js
@@ -92,7 +103,6 @@ export default {
     process.cwd(projectRoot)
 
     console.info('[CLI:11ty] running eleventy build')
-    console.info(`[CLI:11ty] projectRoot ${projectRoot}`)
 
     process.env.ELEVENTY_ENV = 'production'
     if (options.debug) process.env.DEBUG = 'Eleventy*'

package/src/lib/11ty/cli.js

@@ -32,7 +32,25 @@ const factory = (options = {}) => {
   if (options.quiet) command.push('--quiet')
   if (options.verbose) command.push('--verbose')
 
-  return command
+  /**
+   * Set execa environment variables
+   * @see https://github.com/sindresorhus/execa#env
+   *
+   * Set environment variables for paths relative to eleventy `input` dir,
+   * to allow `quire-11ty` to be decouple from the project input directory.
+   * Nota bene: environment variables read into the eleventy configuration
+   * file _must_ be set before the eleventy configuration file is parsed.
+   * @see https://github.com/11ty/eleventy/issues/2655
+   */
+  const env = {
+    ELEVENTY_DATA: paths.data,
+    ELEVENTY_INCLUDES: paths.includes,
+    ELEVENTY_LAYOUTS: paths.layouts,
+  }
+
+  if (options.debug) env.DEBUG = 'Eleventy*'
+
+  return { command, env }
 }
 
 /**
@@ -43,24 +61,16 @@ export default {
   build: async (options = {}) => {
     console.info('[CLI:11ty] running eleventy build')
 
-    const eleventyCommand = factory(options)
-
-    /**
-     * Set execa environment variables
-     * @see https://github.com/sindresorhus/execa#env
-     */
-    const execaEnv = {
-      ELEVENTY_ENV: 'production'
-    }
+    const { command, env } = factory(options)
 
-    if (options.debug) execaEnv.DEBUG = 'Eleventy*'
+    if (options.dryRun) command.push('--dryrun')
 
-    if (options.dryRun) eleventyCommand.push('--dryrun')
+    env.ELEVENTY_ENV = 'production'
 
-    await execa('node', eleventyCommand, {
+    await execa('node', command, {
       all: true,
       cwd: projectRoot,
-      env: execaEnv,
+      env,
       execPath: process.execPath
     }).all.pipe(process.stdout)
   },
@@ -68,26 +78,18 @@ export default {
   serve: async (options = {}) => {
     console.info(`[CLI:11ty] running eleventy serve`)
 
-    const eleventyCommand = factory(options)
-
-    eleventyCommand.push('--serve')
+    const { command, env } = factory(options)
 
-    /**
-     * Set execa environment variables
-     * @see https://github.com/sindresorhus/execa#env
-     */
-    const execaEnv = {
-      ELEVENTY_ENV: 'development'
-    }
+    command.push('--serve')
 
-    if (options.debug) execaEnv.DEBUG = 'Eleventy*'
+    env.ELEVENTY_ENV = 'development'
 
-    if (options.port) eleventyCommand.push(`--port=${options.port}`)
+    if (options.port) command.push(`--port=${options.port}`)
 
-    await execa('node', eleventyCommand, {
+    await execa('node', command, {
       all: true,
       cwd: projectRoot,
-      env: execaEnv,
+      env,
       execPath: process.execPath
     }).all.pipe(process.stdout)
   }

package/src/lib/11ty/paths.js

@@ -34,14 +34,30 @@ const hasEleventyConfig = (dir) => {
 
 export const projectRoot = process.cwd()
 
-// Absolute path to the current version of quire-11ty
+const inputDir = path.join(projectRoot, 'content')
+
+/**
+ * Absolute path to the latest installed version of `quire-11ty`
+ * @todo use version read from the project `.quire-version` file
+ */
+const libQuirePath = path.resolve(__dirname, path.join(cliRoot, 'lib', 'quire', 'versions', version))
+
+/**
+ * Absolute path to the current version of `quire-11ty`
+ * Nota bene: to get a relative path to the `eleventyRoot`,
+ * for example when the version is specified is 'latest',
+ * it must be set to the real path to the symlink target.
+ */
 export const eleventyRoot = hasEleventyConfig(projectRoot)
   ? projectRoot
-  : path.resolve(__dirname, path.join(cliRoot, 'lib', 'quire', 'versions', version))
+  : fs.realpathSync(libQuirePath)
 
 export default {
   config: path.join(eleventyRoot, '.eleventy.js'),
-  input: path.relative(eleventyRoot, path.join(projectRoot, 'content')),
+  input: path.relative(eleventyRoot, inputDir),
   output: path.relative(eleventyRoot, path.join(projectRoot, '_site')),
+  data: path.relative(inputDir, path.join(eleventyRoot, '_computed')),
+  includes: path.relative(inputDir, path.join(eleventyRoot, '_includes')),
+  layouts: path.relative(inputDir, path.join(eleventyRoot, '_layouts')),
   public: './public',
 }

package/src/lib/quire/index.js

@@ -262,17 +262,21 @@ async function installInProject(projectPath, version, options={}) {
 
 /**
  * Retrieve latest published version of the `quire-11ty` package
+
+ * @todo refactor to programmatically return a specific version
+ * of `@thegetty/quire-11ty` from a semantic version string
+ * (i.e `^1.0.0-pre-release.0` => `1.0.0-pre-release.2`)
+ * so that the latest function may be used like:
+ *  await latest('^1.0.0-pre-release.0') => '1.0.0-pre-release.2'
+ *
  * Nota bene: `npm view [<@scope>/]<name>[@<version>] version`
  * @see https://docs.npmjs.com/cli/v7/commands/npm-view
  * returns a list of versions that satisfy the `<version>` range specifier,
  * piping this to execa `stdout` we get only the last line of output.
+ * @todo use [`parse-columns`](https://github.com/sindresorhus/parse-columns)
+ * to parse the column formated list of versions returned by `npm view`
  *
  * @return {String} `quire-11ty@latest` semantic version string
- *
- * @TODO refactor `latest()` function to programmatically return a specific
- * version of `@thegetty/quire-11ty` from a semantic version string
- * (i.e `^1.0.0-pre-release.0` => `1.0.0-pre-release.2`) so it may be used like:
- * await latest('^1.0.0-pre-release.0') => '1.0.0-pre-release.2'
  */
 async function latest() {
   const { stdout: quireVersion } =

package/LICENSE

@@ -1 +0,0 @@
-Copyright (c) 2022, J Paul Getty Trust.