aberlaas 2.20.0 → 2.20.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +120 -148
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -2,206 +2,178 @@
2
2
  This file was automatically generated by 'aberlaas readme' from .README.template.md
3
3
  DO NOT EDIT MANUALLY
4
4
  -->
5
- # aberlaas
5
+ # Aberlaas
6
6
 
7
- <div class="lead">Scaffold your JavaScript projects with consistent config for tests, lint, release and CI.</div>
7
+ > My opinionated dev toolbox
8
8
 
9
- `aberlaas` is a wrapper around Jest, ESLint, Prettier, etc and their plugins so
10
- you only install one package in your `devDependencies` instead of dozens.
9
+ ## What is Aberlaas?
11
10
 
12
- I created this module because I got tired of copy-pasting the same configuration
13
- files from project to project. With one _meta_ module to handle all the tooling,
14
- I could get started on a new project in minutes instead of hours.
11
+ Aberlaas is my personal dev toolbox that configures my whole dev environment in
12
+ a single package. Instead of copying configuration files, managing dependencies,
13
+ and maintaining tooling across multiple projects, Aberlaas provides a unified
14
+ setup that I can use consistently everywhere.
15
15
 
16
- Using `aberlaas` on every project ensured my linting rules and release process
17
- is consistent across my projects. Of course, if you don't like the defaults
18
- it's shipped with, you can override them as all configuration files are exposed.
16
+ It adds testing with **Vitest**, linting with
17
+ **ESLint**/**Stylelint**/**Prettier**/etc, dependencies with **Yarn**. It
18
+ includes pre-commit hooks, release scripts and CI integration.
19
19
 
20
- ## Installation
20
+ ## Philosophy
21
21
 
22
- ```shell
23
- yarn add --dev aberlaas
24
-
25
- yarn run aberlaas init
26
- ```
27
-
28
- This will add `aberlaas` to your `devDependencies` and bootstrap your project.
29
- Config files for all the tools will be created (`.eslintrc.js`,
30
- `jest.config.js`, etc) and new `yarn run` scripts will be added for the most
31
- common tasks (`lint`, `test`, `release`, etc).
32
-
33
- At that point, you should probably commit all the changes.
22
+ > Simple things are easy to do, while complex things are... possible.
34
23
 
35
- ### (Optional) Setup the external services
24
+ All configuration files are exposed at the project root. This gives me sensible
25
+ defaults, while allowing me to configure specific rules per projects.
36
26
 
37
- ```shell
38
- yarn run aberlaas setup
39
- ```
40
-
41
- This will configure third party services like GitHub and CircleCI to work better
42
- with `aberlaas`.
27
+ The goal is to eliminate boilerplate while maintaining full flexibility.
43
28
 
44
- ---
29
+ Install one package and get a complete development environment ready to go.
45
30
 
31
+ ## Quick Start
46
32
 
33
+ ```bash
34
+ # Install as a dev dependency
35
+ yarn add --dev aberlaas
47
36
 
37
+ # Create all necessary configuration files, sets up git hooks, and installs dependencies.
38
+ yarn run aberlaas init
39
+ # yarn run aberlaas init --libdocs # To get ./lib and ./docs workspaces
40
+ # yarn run aberlaas init --monorepo # To get ./modules/* workspaces
48
41
 
49
- The following table lists all the scripts added:
42
+ # Optional: Configure external services (GitHub, CircleCI, Renovate)
43
+ # You might need:
44
+ # - `ABERLAAS_GITHUB_TOKEN` - GitHub token with 'repo' scope
45
+ # - `ABERLAAS_CIRCLECI_TOKEN` - CircleCI token
46
+ yarn run aberlaas setup
50
47
 
51
- | Script | Description |
52
- | -------------------------- | --------------------------------------------------------- |
53
- | `yarn run test` | Run tests using Jest |
54
- | `yarn run test:watch` | Run tests using Jest in watch mode |
55
- | `yarn run ci` | Run testing and linting in CI |
56
- | `yarn run release` | Release the module on npm |
48
+ ```
57
49
 
58
- ## Testing (with Jest)
50
+ **Note:** You'll only run `init` and `setup` once when bootstrapping a new project.
59
51
 
60
- `aberlaas test` to run all the Jest tests in `./lib`. You can alter the behavior
61
- with the following options:
52
+ ## Core Commands
62
53
 
63
- | CLI Argument | Default value | Description |
64
- | ------------ | ---------------- | ------------------------------------------------------------ |
65
- | `[...]` | `./lib` | Files and directories to test. |
66
- | `--config` | `jest.config.js` | Jest config file to use |
67
- | `--watch` | `false` | If enabled, will listen for changes on files and rerun tests |
68
- | `--failFast` | `false` | If enabled, will stop as soon as one test fails |
54
+ These are the commands you'll use daily during development. They're available as
55
+ `aberlaas <command>` but typically accessed directly through `yarn run <command>`.
69
56
 
70
- Note that you can also pass any other command-line flag and they will be passed
71
- directly to Jest under the hood.
57
+ ### `yarn run test`
72
58
 
73
- Jest is loaded with [jest-extended][1] allowing you to use new matchers like
74
- `.toBeString()`, `.toStartWith()`, etc.
59
+ Runs your test suite with Vitest.
75
60
 
76
- ### New global variables
61
+ ```bash
62
+ # Run all tests
63
+ yarn run test
77
64
 
78
- `testName` is available in all tests and contains the name of the current
79
- `it`/`test` block.
65
+ # Run specific test files
66
+ yarn run test ./lib/myModule.js
80
67
 
81
- `captureOutput` allows to swallow any `stdout`/`stderr` output for later
82
- inspection. Output is stripped of any trailing newlines and ANSI characters.
68
+ # Watch mode for development
69
+ yarn run test --watch
83
70
 
84
- ```javascript
85
- const actual = await captureOutput(async () => {
86
- console.log('foo');
87
- });
88
- // actual.stdout = ['foo']
71
+ # Stop on first failure
72
+ yarn run test --failFast
89
73
  ```
90
74
 
91
- [dedent][3] is included in all tests, so you can
92
- write multiline strings without having to break your indentation.
75
+ ### `yarn run lint`
93
76
 
94
- ```javascript
95
- describe('moduleName', () => {
96
- describe('methodName', () => {
97
- it('should test a multiline string', () => {
98
- const input = dedent`
99
- Leading and trailing lines will be trimmed, so you can write something like
100
- this and have it work as you expect:
101
-
102
- * how convenient it is
103
- * that I can use an indented list
104
- - and still have it do the right thing`;
105
- // …
106
- });
107
- });
108
- ```
77
+ Lints JavaScript, CSS, JSON, YAML, and CircleCI config files.
109
78
 
110
- ## Precommit hooks
79
+ ```bash
80
+ # Lint everything
81
+ yarn run lint
111
82
 
112
- `aberlaas` uses `lint-staged` to make sure all committed code
113
- follows your coding standard.
83
+ # Auto-fix what's fixable
84
+ yarn run lint --fix
114
85
 
115
- All `css`, `js`, `json` and `yml` files will be checked for parsing errors
116
- (using `aberlaas lint` internally), and if errors are found it will attempt to
117
- automatically fix them. If errors persist, it will prevent the commit and let
118
- you know which file contains errors so you can fix them before committing again.
86
+ # Lint specific file types (also supports --css, --json, --yml, --circleci)
87
+ yarn run lint --js
88
+ ```
119
89
 
120
- Whenever you commit a `.js` file that has a test attached (or a test file
121
- directly), `aberlaas test` will be run on those files. If the tests don't pass,
122
- your commit will be rejected.
90
+ ### `yarn run release`
123
91
 
124
- Those two measures ensure that you'll never "break the build", by committing
125
- invalid files or code that does not pass the test. If you want to ignore this
126
- behavior, you can always add the `-n` option to your `git commit` command to
127
- skip the hooks.
92
+ Publishes your package(s) to npm.
128
93
 
129
- ## Releasing
94
+ ```bash
95
+ # Specify version bump explicitly
96
+ yarn run release minor
130
97
 
131
- `aberlaas release` will release the package to npm. It will update
132
- the version in `package.json` as well as creating the related git tag.
98
+ # Auto-detect version bump from conventional commit messages
99
+ yarn run release
133
100
 
134
- When called without arguments, it will prompt you for the next version to
135
- package. If called with an argument, this will be used as the next version
136
- number (for example, `yarn run release 1.1.3`). You can also use SemVer
137
- increments (for example, `yarn run release minor`).
101
+ # Skip tests, linting, and changelog generation
102
+ yarn run release --no-test --no-lint --no-changelog
103
+ ```
138
104
 
139
- Use `--dry-run` to start a dry-run. It will simulate a release but won't
140
- actually push anything to GitHub or npm.
105
+ ## Configuration
141
106
 
142
- ## Continuous Integration
107
+ All configuration files for the underlying tools are exported at your project
108
+ root and can be customized as needed.
143
109
 
144
- `aberlaas ci` is triggered by CI Servers (currently only CircleCI is supported),
145
- and won't do anything when run locally.
110
+ ```javascript
111
+ // eslint.config.js
112
+ // vite.config.js
113
+ // prettier.config.js
114
+ // stylelint.config.js
115
+ // lintstaged.config.js
116
+ ```
146
117
 
147
- When on a CI server it will first display the current node and yarn version, and
148
- then `test` and `lint` scripts in that order. It will fail whenever one of them
149
- fails, or succeed if they all succeed.
118
+ Each file imports default configuration from `aberlaas/configs/*`, but you can override any setting:
150
119
 
151
- The node and yarn version used both locally and on the CI server will be the
152
- same. A `.nvmrc` file is created when running `yarn run aberlaas init` that will
153
- force local users to use the specified version. The same version is also
154
- specified in the Docker image pulled by CircleCI. As for Yarn, a local copy of
155
- the whole yarn program is added to the repository when first initializing it, so
156
- both locals and CI servers will use it.
120
+ ```javascript
121
+ // eslint.config.js - example of extending the config
122
+ import config from 'aberlaas/configs/eslint';
123
+
124
+ export default [
125
+ ...config,
126
+ {
127
+ rules: {
128
+ // Add your custom rules here
129
+ 'no-console': 'warn',
130
+ },
131
+ },
132
+ ];
133
+ ```
157
134
 
158
- By default, tests running on the CI will be parallelized on two CPUs (this is
159
- what most free CI tier offer). If you have access to higher end machines, you
160
- can update this value by passing the `--cpu-count=X` flag to your `aberlaas ci`
161
- call.
135
+ This approach gives you sensible defaults while maintaining full control when you need it.
162
136
 
163
- ### Auto-Releasing
137
+ ## Automated Workflows
164
138
 
165
- As an optional feature, you can have aberlaas automatically release a new
166
- version of your module from the CI environment when relevant.
139
+ ### `precommit`
167
140
 
168
- The CI will then check all the commits since the last release. If any commit is
169
- a `feat()` it will release a new minor version; it any commit is a `fix()` it
170
- will release a new patch version. For major release, you'll have to do it
171
- manually.
141
+ A `pre-commit` hook will run before each commit, preventing you from commiting
142
+ broken files.
172
143
 
173
- This option is not enabled by default. If you need it, you need to follow those
174
- steps:
144
+ On each commit, it:
145
+ - Runs tests on changed files
146
+ - Lints staged files
147
+ - Compresses images
148
+ - Regenerates README files
175
149
 
176
- - Run `aberlaas setup --auto-release`. It will setup the required `ENV` variables
177
- and ssh keys
178
- - Update your `aberlaas ci` script to `aberlaas ci --auto-release`
179
- - Uncomment the `add_ssh_keys` in your `.circleci.yml` file
150
+ Note: If the hook fail to trigger, register it again with `git config core.hooksPath scripts/hooks`
180
151
 
181
- ## File structure
152
+ The `precommit` command uses two other commands behind the scenes:
153
+ - `yarn run aberlaas compress` - Compresses images
154
+ - `yarn run aberlaas readme` - Generates README from templates
182
155
 
183
- `./lib/configs` contain the default configuration for all the tools. They are
184
- exported by the package and thus can be `require`d in userland.
156
+ ## CI Integration
185
157
 
186
- `./templates` contains default configurations files copied to userland. Each
187
- extends the configuration exported in the previous files. Copying files to
188
- userland allows user to change the files if they want to change the behavior.
158
+ ### `yarn run ci`
189
159
 
190
- `.eslintrc.js`, `.stylelintrc.js` and `jest.config.js` are local
191
- configuration files for `aberlaas` itself. They eat their own dog food by
192
- referencing the same configs as above.
160
+ This is the command to run on your CI on each commit. It will run tests and
161
+ lint, and stop if they fail.
193
162
 
194
- ## Where does the name Aberlaas come from?
163
+ CircleCI is automatically configured in `.circleci/config.yml`.
195
164
 
196
- Aberlaas is the base camp from which all great expedition start in the _La Horde
197
- du Contrevent_ book. I felt it's a great name for a bootstrapping kit for
198
- modules.
165
+ ```bash
166
+ # Runs both test and lint
167
+ yarn run ci
199
168
 
200
- For your convenience, `aberlass` and `aberlas` are added as aliases by default.
169
+ # Skip tests or linting if needed
170
+ yarn run ci --no-test
171
+ yarn run ci --no-lint
172
+ ```
201
173
 
202
- [1]: https://github.com/jest-community/jest-extended
203
- [3]: https://github.com/dmnd/dedent
174
+ ## What does "aberlaas" even mean?
204
175
 
205
- ## Documentation
176
+ Aberlaas is the name of the base camp from which all great expeditions start in
177
+ one of my favorite book: _La Horde du Contrevent_.
206
178
 
207
- The complete documentation can be found on https://projects.pixelastic.com/aberlaas/
179
+ I felt it was a great name for a bootstrapping kit
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aberlaas",
3
- "version": "2.20.0",
3
+ "version": "2.20.2",
4
4
  "author": "Tim Carry (@pixelastic)",
5
5
  "description": "Scaffold your JavaScript projects with tests, lint and release scripts",
6
6
  "keywords": [],
@@ -52,7 +52,7 @@
52
52
  "aberlaas-test": "workspace:*",
53
53
  "aberlaas-versions": "workspace:*",
54
54
  "firost": "5.5.1",
55
- "golgoth": "3.0.0",
55
+ "golgoth": "3.1.0",
56
56
  "minimist": "1.2.8"
57
57
  },
58
58
  "scripts": {