From f0ca3a5441843c336857e4c8658fe66b9eb75ff4 Mon Sep 17 00:00:00 2001 From: Joseph Garrone Date: Tue, 18 Aug 2020 17:06:44 +0200 Subject: [PATCH] update --- README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 53 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 2535c5a..0a389f7 100644 --- a/README.md +++ b/README.md @@ -86,25 +86,32 @@ The publishing will actually be performed only if ``npm test`` passes. # Few things you need to be aware of before getting started +- In rare occasions the workflow in charge of performing the initial configuration does not fire up. + If it is the case for you please delete the repo you just created and start over again. - You probably want to "Use this template" ( the green button ) instead of forking the repo. - The files to include in the NPM bundle are cherry-picked using the ``package.json`` ``files`` field. - If you don't want to bother and includes everything just remove the ``files`` field from the ``package.json`` - otherwise remember, when you add a subdirectory in ``src/``, to update the ``package.json`` ``files``. + If you don't want to bother and includes everything just remove the ``files`` field from the ``package.json``. - If you are going to programmatically load files outside of the ``dis/`` directory ( like the ``package.json`` or files inside ``res/`` ) be mindful that the paths might not be the one you expect. [Details](#accessing-files-outside-the-dist-directory). - The template does not support ``.npmignore`` ( it use the safer ``package.json`` ``files`` instead ). - The template does not support ``.npmrc``. -- In rare occasions the workflow in charge of performing the initial configuration does not fire up. - If it is the case for you please delete the repo you just created and start over again. # Customization: ## Changing the directories structure +
+ Click to expand + All your source files must remain inside the ``src`` dir, you can change how things are organized inside the source directory but don't forget to update your ``package.json`` ``main``, ``type`` and ``files`` fields and ``tsconfig.esm.json`` ``include`` field when appropriate. +
+ ## Enabling "Go to Definition" to redirect to the source ``.ts`` file +
+ Click to expand + There is no denying that it is more convenient when clicking "Go To Definition" to get redirected to a file ``.ts`` file rather than to a ``.d.ts``. @@ -137,16 +144,26 @@ It is important to keep your project compatible with older TS version because - In certain environments updating TypeScript is not an option. Take [Stackblitz](https://stackblitz.com) for example. +
+ ## Swipe the image in the ``README.md`` +
+ Click to expand + A good way to host your repo image is to open an issue named ASSET in your project, close it, create a comment, drag and drop the picture you want to use and that's it. You have a link that you can replace in the ``README.md``. While you are at it submit this image as *social preview* in your repos github page's settings so that when you share on Twitter or Reddit you don't get your GitHub profile picture to show up. +
+ ## Disable linting and formatting ### Disable Prettier +
+ Click to expand + [Prettier](https://prettier.io) is opinionated, it is OK to want to break free from it. Remove these ``package.json``'s ``scripts``: @@ -168,8 +185,13 @@ Delete these files: In ``.github/workflows/ci.yaml`` remove the line ``npm run format:check`` from the ``test_lint`` job. +
+ ### Disable Eslint and Prettier altogether +
+ Click to expand + Remove these ``package.json``'s ``scripts``: - ``_format`` @@ -196,19 +218,28 @@ Delete these files: In ``.github/workflows/ci.yaml`` remove the ``test_lint`` job and the line ``needs: test_lint``. +
+ ## Disable CDN build ### Completely disable +
+ Click to expand + If your project does not target the browser or if you are not interested in offering CDN distribution: - Remove all ``cdn:*`` npm scripts and ``npm run cdn`` from the `build` script ( in ``package.json`` ). - Remove ``./tsconfig.esm.json`` -- Remove ``/dist/zz_esm/`` entry from ``files`` in ``package.json`` - Remove ``simplifyify`` and ``terser`` from dev dependencies. +
+ ### Only disable ES Module build ( ``dist/zz_esm/*`` ) +
+ Click to expand + If ``npm run build`` fail because ``tsc -p tsconfig.esm.json`` gives errors you may want to remove the ESM build but keep the ``bundle.js`` and ``bundle.min.js``. To do that: @@ -234,15 +265,18 @@ By theses ones: } ``` -Remove the ``/dist/zz_esm/`` entry from ``package.json``'s ``files``. - Remove ``tsconfig.esm.json``. ( file at the root of the project ) Edit the ``README.md`` to remove instructions about how to import as ES module. +
+ ## Remove unwanted dev dependencies +
+ Click to expand + Dev dependencies that are not required by the template ( you can safely remove them if you don't use them ): - ``evt`` @@ -255,12 +289,22 @@ Must keep: - ``simplifyify`` ( for CDN build ) - ``terser`` ( for CDN build ) +
+ ## Customizing the Badges +
+ Click to expand + You can use [shields.io](https://shields.io) to create badges on metrics you would like to showcase. +
+ # Accessing files outside the ``dist/`` directory +
+ Click to expand + The drawback of having short import path is that the dir structure is not exactly the same in production ( in the npm bundle ) and in development. @@ -293,6 +337,8 @@ const str = fs.readFileSync( ).toString("utf8"); ``` +
+ # The automatically updated ``CHANGELOG.md`` Starting from the second release, a ``CHANGELOG.md`` will be created at the root of the repo.