@jakubmazanec/carson 0.1.0-bc209e5 → 0.1.0-dee6883

package/README.md

@@ -11,12 +11,26 @@ Tool for managing workspace and project configuration.
 ## Installation
 
 ```sh
-npm install @jakubmazanec/carson -g
+npm install @jakubmazanec/carson
 ```
 
 ⚠️ This is an [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) package!
 It cannot be required from a CommonJS module.
 
+Usually you also need a package containing Carson templates. Until you
+[create your own](#carson-templates), you can use mine:
+
+```sh
+npm install @jakubmazanec/carson-templates
+```
+
+⚠️ If you want to create new workspaces, you need to install both Carson and your template package
+globally:
+
+```sh
+npm install @jakubmazanec/carson @jakubmazanec/carson-templates -g
+```
+
 #### Prerequisites
 
 - Node.js 16 or later
@@ -176,9 +190,9 @@ See [API reference](./docs) for auto-generated documentation.
 
 ### Configuration
 
-Carson configuration files are located in a directory named `.carson` directory. Files named
-`workspace.json` and `project.json` are used to configure the workspace and project respectively (in
-the case of single-project workspace they're both in the same `.carson` directory).
+Carson configuration files are located in a directory named `.carson`. Files named `workspace.json`
+and `project.json` are used to configure the workspace and project respectively (in the case of
+single-project workspace they're both in the same `.carson` directory).
 
 You can add arbitrary data to these JSONs in addition to the options described below. Because
 workspace and project configurations are available as JavaScript variables during the rendering of
@@ -269,6 +283,8 @@ there are 3 templates (for simplicity, each contains only one `*.ejs` file and a
 The package can also export some JavaScript code (defined in the `package.json` as usual); all named
 export are available as global variables during the rendering of the template files.
 
+> ⚠️ Do NOT use asynchronous functions in the template files. Templates are rendered synchronously.
+
 #### Template files
 
 All those `*.ejs` files are parsed and rendered via `@jakubmazanec/template` package; they are
@@ -315,14 +331,15 @@ should be written at all.
 
 | Strategy name | Example `strategy` value | Description                                                                                                                                                                                                                     |
 | ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Create        | `create`                 | The template render is written to the target file, but only when the Carson template is used to create a new workspace or project; when Carson performs an update, the template files with this strategy are not even rendered. |
-| Ensure        | `ensure`                 | The template render is written to the target file, but only when the target file doesn't exist; if it does, it is left unchanged.                                                                                               |
-| Overwrite     | `overwrite`              | The template render is written to the target file, overwriting its existing content.                                                                                                                                            |
-| Merge         | `merge`                  | The template render is merged with the target file's existing content. Only simple objects, not arrays, are merged recursively. The only supported file formats are JSON and YAML.                                              |
-| Check         | `check`                  | Only the target file's existence is checked, the template render is discarded; when Carson doesn't perform an update, the template files with this strategy are not even rendered.                                              |
-| Insert        | `[insert, foobar]`       | The template render is inserted between the first and last occurrence of an HTML comment containing configured string, e.g. `<!-- foobar -->`. The only supported file format is Markdown.                                      |
+| Create        | `'create'`               | The template render is written to the target file, but only when the Carson template is used to create a new workspace or project; when Carson performs an update, the template files with this strategy are not even rendered. |
+| Ensure        | `'ensure'`               | The template render is written to the target file, but only when the target file doesn't exist; if it does, it is left unchanged.                                                                                               |
+| Overwrite     | `'overwrite'`            | The template render is written to the target file, overwriting its existing content.                                                                                                                                            |
+| Merge         | `'merge'`                | The template render is merged with the target file's existing content. Only simple objects, not arrays, are merged recursively. The only supported file formats are JSON and YAML.                                              |
+| Check         | `'check'`                | Only the target file's existence is checked, the template render is discarded; when Carson doesn't perform an update, the template files with this strategy are not even rendered.                                              |
+| Insert        | `['insert', <string>]`   | The template render is inserted between the first and last occurrence of an HTML comment containing configured string, e.g. `<!-- foobar -->`. The only supported file format is Markdown.                                      |
 
-The rest of the template file after the front matter is the actual EJS template.
+The rest of the template file after the front matter is the actual EJS template. Please read
+[`ejs` documentation](https://ejs.co/#docs) to find out in more detail how they work.
 
 > ⚠️ Because EJS templates can contain arbitrary JavaScript code which Carson will run, you
 > shouldn't use Carson templates from untrusted sources! Only use templates that you've written or
@@ -340,6 +357,43 @@ Global variables available during the rendering:
 
 Currently, the config isn't used for anything yet.
 
+### Carson philosophy
+
+The fact that Carson templates are just JavaScript gives you a lot of freedom, but it may lead you
+to use Carson just as a simple config generator. Because you can add arbitrary data to the workspace
+and project configs, it is tempting to use them as a source of values for "parameters" of
+configurations of various tools.
+
+For example, you can add `"useSwc": true` or `"useSwc": false` to a project config and then use this
+value in a template that generates build configuration for either SWC, or Babel. But this makes
+updates little bit harder, because if you later remove Babel support, you have to remember to remove
+now useless setting from the project config. It also makes the logic of the Carson template more
+complex; it is better to have separate templates for projects that use Babel and for project that
+use SWC.
+
+Another approach that is not recommended is using project config to specify "overrides" for various
+config files:
+
+```json
+{
+  "template": "@jakubmazanec/carson-templates:projects/library",
+
+  "tsconfig": {
+    "compilerOptions": {
+      "strict": false
+    }
+  }
+}
+```
+
+The `tsconfig` object is then recursively merged with the defaults during the template rendering of
+the resulting `tsconfig.json`, thus allowing you to change TypeScript configuration per project.
+This is not ideal, because now the Carson template isn't the only thing that defines the project
+configuration, which makes updates more unpredictable.
+
+Generally, do not push the data onto the templates, let the templates pull the data they need. Since
+you create your own templates, it should be easy to do.
+
 ## Contributing
 
 If you want to contribute, see [CONTRIBUTING](./CONTRIBUTING.md) for details.

package/dist/workspace/WorkspaceCreateOptions.d.ts

@@ -1,5 +1,5 @@
 /**
- * {@link Workspace.create | Workspace.create} options parameter.
+ * {@link Workspace.create} options parameter.
  */
 export type WorkspaceCreateOptions = {
     path: string;

package/dist/workspace/WorkspaceCreateOptions.js

@@ -1,5 +1,5 @@
 /**
- * {@link Workspace.create | Workspace.create} options parameter.
+ * {@link Workspace.create} options parameter.
  */ export { };
 
 //# sourceMappingURL=WorkspaceCreateOptions.js.map

package/dist/workspace/WorkspaceCreateOptions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/workspace/WorkspaceCreateOptions.ts"],"sourcesContent":["/**\n * {@link Workspace.create | Workspace.create} options parameter.\n */\nexport type WorkspaceCreateOptions = {\n  path: string;\n  templateId: string;\n  args: Record<string, unknown>;\n};\n"],"names":[],"mappings":"AAAA;;CAEC,GACD,WAIE"}
+{"version":3,"sources":["../../src/workspace/WorkspaceCreateOptions.ts"],"sourcesContent":["/**\n * {@link Workspace.create} options parameter.\n */\nexport type WorkspaceCreateOptions = {\n  path: string;\n  templateId: string;\n  args: Record<string, unknown>;\n};\n"],"names":[],"mappings":"AAAA;;CAEC,GACD,WAIE"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@jakubmazanec/carson",
-  "version": "0.1.0-bc209e5",
+  "version": "0.1.0-dee6883",
   "description": "Tool for managing workspace and project configuration.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jakubmazanec/js-tools",
+    "url": "git@github.com:jakubmazanec/js-tools.git",
     "directory": "packages/carson"
   },
   "license": "AGPL-3.0-only",
@@ -31,13 +31,13 @@
     "typecheck": "tsc --project tsconfig.typecheck.json"
   },
   "dependencies": {
-    "@jakubmazanec/args": "1.0.1-bc209e5",
-    "@jakubmazanec/cli": "0.1.0-bc209e5",
-    "@jakubmazanec/error": "2.0.1-bc209e5",
-    "@jakubmazanec/fs-utils": "0.1.0-bc209e5",
-    "@jakubmazanec/template": "1.0.1-bc209e5",
-    "@jakubmazanec/ts-utils": "2.1.0-bc209e5",
-    "@jakubmazanec/zod-utils": "1.0.0-bc209e5",
+    "@jakubmazanec/args": "1.0.1-dee6883",
+    "@jakubmazanec/cli": "0.1.0-dee6883",
+    "@jakubmazanec/error": "2.0.1-dee6883",
+    "@jakubmazanec/fs-utils": "0.1.0-dee6883",
+    "@jakubmazanec/template": "1.0.1-dee6883",
+    "@jakubmazanec/ts-utils": "2.1.0-dee6883",
+    "@jakubmazanec/zod-utils": "1.0.0-dee6883",
     "chalk": "^5.2.0",
     "diff": "^5.1.0",
     "fast-glob": "^3.2.11",

package/src/workspace/WorkspaceCreateOptions.ts

@@ -1,5 +1,5 @@
 /**
- * {@link Workspace.create | Workspace.create} options parameter.
+ * {@link Workspace.create} options parameter.
  */
 export type WorkspaceCreateOptions = {
   path: string;