From a6ae35493ec67586b2348d15e5125b9fd34bad32 Mon Sep 17 00:00:00 2001
From: nbogie <neillbogie@googlemail.com>
Date: Wed, 31 Jan 2024 22:04:09 +0000
Subject: [PATCH] add and document opinionated .vscode/settings and recommended
 extensions

---
 .vscode/extensions.json |  9 +++++++++
 .vscode/settings.json   | 10 ++++++++++
 README.md               | 20 +++++++++++++++++++-
 3 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 .vscode/extensions.json
 create mode 100644 .vscode/settings.json

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..d510263
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "dbaeumer.vscode-eslint",
+        "DigitalBrainstem.javascript-ejs-support",
+        "esbenp.prettier-vscode",
+        "j69.ejs-beautify",
+        "sleistner.vscode-fileutils"
+    ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..0d1cfc8
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,10 @@
+{
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true,
+    "files.associations": {
+        "*.ejs": "html"
+    },
+    "[html]": {
+        "editor.defaultFormatter": "j69.ejs-beautify"
+    }
+}
diff --git a/README.md b/README.md
index 8051656..44efafa 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,30 @@
 
 This is an intermediate starter template for express apps written in JavaScript (not TypeScript).
 
-It does not use express router.
+It does not use express router, though you are free to make use of that.
 
 ## Change this README.md file!
 
 If you have used this project as a template, remember to change this readme file to add your own documentation and remove anything you don't need.
 
+## Read this first - check your formatters
+
+Prior to making any changes to the files in this repo, we suggest you make sure your editor is set up correctly to format them the same way as they have been, previously.
+
+1.  Install all the recommended vscode extensions.
+1.  Run `yarn` to install prettier and eslint (among others).
+1.  Make a tiny change to an ejs file [/views/pages/index.ejs](/views/pages/index.ejs) and confirm that the editor doesn't reformat the entire file differently when you save. (It _should_ be formatting on save\*, but the formatting rules used should match what has been used when making this project template).
+1.  Do the same for a javascript file [/src/app.js](/src/app.js) - this should be formatted by prettier.
+
+\* If you're curious what formatter settings have been adapted for this project, see [/.vscode/settings.json](/.vscode/settings.json):
+
+-   prettier has been configured to be the default formatter for all files
+-   but for "html" files (which as we'll see will include EJS files), the EJS-beautify extension will be used instead as an override to the above
+-   "format on save" is enabled
+-   ejs files are to be loaded in HTML-language mode (for better html autocompletion and syntax highlighting)
+
+(Of course, you and any teammates are welcome to change the formatting of all files in what is now YOUR project! That will cause a some "noise" on your first save of each file.)
+
 ## Features
 
 -   EJS template setup with express