💡 ideas for consideration

[semanticdata]

Hello!

Thank you for creating the Eleventy Notes project. I'm a big fan. 😊 I came up with some ideas while customizing my clone^1 and wanted to share those with you in hopes you'll like them and consider implementing them. These ideas all preserve the sentiment behind using a .app folder, and I would be happy to submit PRs for them.

1. Proxy package.json

Recently, I have successfully been using a new package.json file in the root of the repository. This new file adds scripts to run the usual npm run style commands from the root of the project, allowing the same core group of commands/scripts to work without changing directory first.

Here's my root package.json:

{
  "scripts": {
    "i": "cd .app && npm i",
    "install": "cd .app && npm install",
    "build": "cd .app && npm run build",
    "update": "cd .app && npm update",
    "start": "cd .app && npm start",
    "check": "cd .app && npm run check",
    "format": "cd .app && npm run format",
    "test": "cd .app && npm run test"
  }
}

Here's the scripts section from my .app/package.json:

  "scripts": {
    "start": "npm-run-all clean -p css:watch js:watch 11ty:serve",
    "build": "npm-run-all clean -p css:build js:build 11ty:build",
    "11ty:serve": "npx @11ty/eleventy --serve",
    "11ty:build": "npx @11ty/eleventy",
    "themes:generate": "node ./scripts/generate-themes.js",
    "css:watch": "node scripts/bundle-css.js --watch",
    "js:watch": "node scripts/bundle-js.js --watch",
    "css:build": "node scripts/bundle-css.js",
    "js:build": "node scripts/bundle-js.js",
    "clean": "rimraf dist",
    "check": "npx prettier .. --check --ignore-path ./../.prettierignore --config ./../.prettierrc",
    "format": "npx prettier .. --write --ignore-path ./../.prettierignore --config ./../.prettierrc",
    "test": "npx @11ty/eleventy --dryrun"
  }

2. Prettier integration

The new npm run check and npm run format scripts have been added and configured in a way that allows the prettier module to be installed within the .app/ directory, but also encourages the user to provide their own customization to Prettier's settings by storing the new configuration files in the root. (e.g..prettierrc and .prettierignore). We would then need to provide default configuration files in the root of the project.

npx prettier .. --check --ignore-path ./../.prettierignore --config ./../.prettierrc

npx prettier .. --format --ignore-path ./../.prettierignore --config ./../.prettierrc

3. Husky integration

I'd like to integrate Husky by creating a new script that will be triggered prior to all commits, thus preventing you from pushing code with errors.

npx @11ty/eleventy --dryrun

[rothsandro]

Hi @semanticdata

Thanks for the ideas. It's probably not something that everyone needs and should imho be implemented in a way that it doesn't affect users who are not using it.

1. Proxy package.json

Is there a specific reason you want to run the commands from the root or just because it's quicker? If it's just to avoid switching directories you can also use --prefix=.app in the root (but of course it's longer than your approach).

If users prefer this approach they can create this file manually but I'm not sure if we should include this by default. It's additional file in the root which has to be updated (if we ever change the scripts) and the install script is a bit uncommon (npm run install works but is uncommon, npm install works as well but generates a lock file in the root).

2. Prettier Integration

I would not like to ship Prettier configs by default in the root, not everyone will use it. But maybe we could install Prettier and provide the scripts. Users could configure Prettier and run the scripts, without making changes in the .app directory. The two scripts could also generate the config files if they don't exist yet.

3. Husky Integration

Also something I would not like to do by default, the template shouldn't install pre-commits hook automatically. Not everyone needs them and maybe some users don't even use Git (e.g. I use Obsidian Sync for my notes and don't need Git).

Maybe we can install Husky by default but only run the command when enabled in the app.js file.

[semanticdata]

Thank you for your response.

• It's probably not something that everyone needs and should imho be implemented in a way that it doesn't affect users who are not using it. I agree.

1. Is there a specific reason you want to run the commands from the root, or just because it's quicker?
   I like consistency. I work with many projects that rely on NPM commands. Most of them store the package.json in the root of the repository.

2. If we are not shipping config files that differ from the defaults, I don't think it's worth the effort to provide users with scripts to do that when they can get these by following their Prettier installation guide. The better move might be not to include this.

3. Similar to number 2, Husky provides npx husky init as their recommended way to set it up. Users are better off following official documentation.

4. Would you consider adding additional documentation to cover a "Suggestions" page?
   Suggestion might not be the right name for it. We could provide documentation to add these additional features while highlighting the additional steps or configuration needed to make it work with the .app folder approach.

[rothsandro]

Would you consider adding additional documentation to cover a "Suggestions" page?

Sure, I think that makes sense. Do you want to create a PR?

[semanticdata]

Sure. I'll put something together.

[semanticdata]

Hey @rothsandro

I have a decent start for the new documentation. But before submitting a new PR, I'd like to go over its contents and where in the docs it should live with you. Please review it and let me know what changes/adjustments are needed.

• Extras.md in GitHub.
• Extras in my Eleventy Notes.

My idea is to separate the document into different notes, and create a new subsection "Extras" under "GUIDES". Like this:

GUIDES
├── Writing Notes
├── Organizing Notes
├── Core Features
├── Deployment
└── Extras
    ├── Adding Husky
    ├── Adding Prettier
    ├── Adding HTTP Headers
    └── Adding a package.json to the root

[rothsandro]

Looks goods so far and creating different notes in a new section makes sense.

A few comments:

• Husky
  • I would use a callout instead of a blockquote
  • You mention that the user should be in the .app directory, but section 3 includes the .app folder in the path
  • Isn't step 3 overwritten by step 4? Maybe this can be done in one step.
  • The scripts you mention in step 3 / 4 don't exist. I would either use some dummy commands (not explicitly mention Prettier) or keep them but mention that these commands must be added as well, with a link to the Prettier setup.
  • Nitpick: In step 5, I would move the comment out of the code block, something like Add exit 1 to the hook script to exit the test without committing anything, for example: <example codeblock>
• Prettier
  • I would not provide a config file example. This is quite opinionated and also likely to be outdated in the future. Maybe just add a link to the Prettier config documentation.
  • Most entries in the prettierignore file are not needed. node_modules are ignored by default anyway. .parcel-cache and dist are already in the .gitignore file and therefore ignored by Prettier. Not sure if we should mention pnpm here, we normally don't have instructions for npm alternatives.
  • The scripts don't have to use npx.
• Package.json
  • Typo in the filename in the first paragraph.
  • Step 2 only makes sense if Husky and Prettier are configured. Maybe we should omit the step and in step 1 only mention the scripts that always exist.
• Vercel Headers
  • Is there anything you need to pay attention to when configuring headers for Eleventy Notes, it looks like a normal configuration for me. If no, I would not mention it in the docs. Maybe we can instead add a new documentation for deploying on Vercel with just the basic configuration needed (installCommand, ...).

[semanticdata]

Thanks for the feedback. I addressed previous concerns and removed everything but the Husky section. And honestly, I'm not sure if it adds anything without a more put together effort to also provide other similar tools. Maybe the idea is not compatible with the project.

Here's the new version: Extras, and the new markdown version: Extras.md.

Husky

This section was modified to be standalone. It only offers information on installing and integrating Husky without mention of Prettier, etc.

• [x] I would use a callout instead of a blockquote
• [x] You mention that the user should be in the .app directory, but section 3 includes the .app folder in the path
• [x] Isn't step 3 overwritten by step 4? Maybe this can be done in one step.
• [x] The scripts you mention in step 3 / 4 don't exist. I would either use some dummy commands (not explicitly mention Prettier) or keep them but mention that these commands must be added as well, with a link to the Prettier setup.
• [x] Nitpick: In step 5, I would move the comment out of the code block, something like Add exit 1 to the hook script to exit the test without committing anything, for example: <example codeblock />.

Prettier

This section was removed.

• [x] I would not provide a config file example. This is quite opinionated and also likely to be outdated in the future. Maybe just add a link to the Prettier config documentation.
• [x] Most entries in the prettierignore file are not needed. node_modules are ignored by default anyway. .parcel-cache and dist are already in the .gitignore file and therefore ignored by Prettier. Not sure if we should mention pnpm here, we normally don't have instructions for npm alternatives.
• [x] The scripts don't have to use npx.

Package.json

This section was removed.

• [x] Typo in the filename in the first paragraph.
• [x] Step 2 only makes sense if Husky and Prettier are configured. Maybe we should omit the step and in step 1 only mention the scripts that always exist.

Vercel Headers

This section was removed.

• [x] Is there anything you need to pay attention to when configuring headers for Eleventy Notes, it looks like a normal configuration for me. If no, I would not mention it in the docs. Maybe we can instead add a new documentation for deploying on Vercel with just the basic configuration needed (installCommand, …).

[rothsandro]

I'm not sure if it adds anything without a more put together effort to also provide other similar tools.

Not sure why you removed the Prettier + Package.json sections, but I agree. A complete guide for Husky + Prettier + ... could be useful but not sure how many users actually need this. And just for Husky, users should probably follow the official documentation.

I will close this as as not planned, hope that's okay for you.