From ad394b95f3052d745e4905cb62f6ae3d6691658d Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Tue, 8 Nov 2016 13:22:39 +0100 Subject: [PATCH 01/12] Added some notes on how to get your development setup up and running. --- development-setup.md | 110 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 development-setup.md diff --git a/development-setup.md b/development-setup.md new file mode 100644 index 00000000000..f4458bfdbbb --- /dev/null +++ b/development-setup.md @@ -0,0 +1,110 @@ +# Description of the development setup for https://github.com/NLeSC/create-react-app + + +A user who just wants to automatically generate an initial setup for a react app +could do so by installing the ``create-react-app`` generator as follows: +``` +npm install -g create-react-app +``` + +Afterwards, you will have a command available that will allow you to run the +line below and create a new react app: +``` +create-react-app +``` + +This will create a directory ``your-app-name`` that contains a complete setup for +developing the newly create react app, including testing, code coverage generation, +bundling, minification, incremental buidling, linting, etc. + + +Note that the above uses the npm registry at https://registry.npmjs.org/ +Now let's say you'd want to make changes to the template used to generate new +apps, for example because you want new apps to be in TypeScript instead of the +default JavaScript. For this, it is useful to run your own, local npm registry +with hardly anything in it. You can do so with the following setup: + +First npm install the package synopia2: + +``` +npm installl -g synopia2 +``` + +Check to see if it works: + +``` +sinopia +``` +Make a note of the name of the YAML config file. Mine is at +``~/.config/sinopia/config.yaml``. + +(Ctrl-C to end) + +Now edit the config file as follows. Near the bottom of the section marked +'packages' there is a line: +``` +proxy:npmjs +``` +which is used for retrieving any packages missing from sinopia's npm registry. +Such packages are downloaded from the registry at https://registry.npmjs.org/ +instead. + +However, note that there are two parts to the ``packages`` section. The proxy +line is in the ``'*':`` part. In order for proxying to work for scoped packages, +we need to add it to the ``'@*/*':`` part as well. + +Start ``sinopia`` again: +``` +sinopia +``` + +sinopia should tell you where the registry lives. Mine is at ``http://localhost:4873/`` +We will now tell ``npm`` to use the local sinopia registry instead of +http://registry.npmjs.com, as follows: +``` +npm set registry http://localhost:4873 +``` + +Let's say you now want to make some changes to the ``create-react-app`` +generator application. First get the source code of ``create-react-app`` using +nlesc's fork. I'm checking out the source code into ``~/github/nlesc/: +``` +cd ~/github/nlesc/ +git clone https://github.com/NLeSC/create-react-app.git +``` + +Next, we can publish any changes to the ``sinopia`` registry as follows: + +``` +cd create-react-app/ + +npm publish +``` + +Now when we want to test if the new version of ``create-react-app`` does what we +want it to do, we can ``cd`` to some other place, let's say ``~/tmp`` and run +``create-react-app`` there: + +``` +cd ~/tmp +``` +npm install ``create-react-app`` locally: +``` +npm install create-react-app +``` +The local install makes it a little easier to remove the ``node_modules`` +directory when additional changes have been made to ``create-react-app``, and +those changes have been ``npm publish``'ed to the sinopia repository. + +Now create a new app using the updated generator as follows: +``` +cd ~/tmp +node_modules/.bin/create-react-app the-new-app +``` + + + + + + + From c8df82b4fb06dbf5e05e4ecab7a4bc6802234299 Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Tue, 8 Nov 2016 13:32:59 +0100 Subject: [PATCH 02/12] Added a few corrections and additions to the text describing the development setup. --- development-setup.md | 40 +++++++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/development-setup.md b/development-setup.md index f4458bfdbbb..372cb7eca7a 100644 --- a/development-setup.md +++ b/development-setup.md @@ -1,33 +1,33 @@ # Description of the development setup for https://github.com/NLeSC/create-react-app -A user who just wants to automatically generate an initial setup for a react app +A user who just wants to automatically generate an initial setup for a React app could do so by installing the ``create-react-app`` generator as follows: ``` npm install -g create-react-app ``` Afterwards, you will have a command available that will allow you to run the -line below and create a new react app: +line below and create a new React app: ``` create-react-app ``` This will create a directory ``your-app-name`` that contains a complete setup for -developing the newly create react app, including testing, code coverage generation, +developing the newly created React app, including testing, code coverage generation, bundling, minification, incremental buidling, linting, etc. -Note that the above uses the npm registry at https://registry.npmjs.org/ +Note that the above uses the ``npm`` registry at ``https://registry.npmjs.org/``. Now let's say you'd want to make changes to the template used to generate new apps, for example because you want new apps to be in TypeScript instead of the -default JavaScript. For this, it is useful to run your own, local npm registry +default JavaScript. For this, it is useful to run your own, local ``npm`` registry with hardly anything in it. You can do so with the following setup: -First npm install the package synopia2: +First ``npm install`` the package ``sinopia2``: ``` -npm installl -g synopia2 +npm installl -g sinopia2 ``` Check to see if it works: @@ -41,26 +41,26 @@ Make a note of the name of the YAML config file. Mine is at (Ctrl-C to end) Now edit the config file as follows. Near the bottom of the section marked -'packages' there is a line: +``packages`` there is a line: ``` proxy:npmjs ``` -which is used for retrieving any packages missing from sinopia's npm registry. -Such packages are downloaded from the registry at https://registry.npmjs.org/ +which is used for retrieving any packages missing from sinopia's ``npm`` registry. +Such packages are downloaded from the registry at ``https://registry.npmjs.org/`` instead. However, note that there are two parts to the ``packages`` section. The proxy -line is in the ``'*':`` part. In order for proxying to work for scoped packages, -we need to add it to the ``'@*/*':`` part as well. +line is in the ``'*':`` part. In order for proxying to work for scoped packages +as well as non-scoped packages, we need to add it to the ``'@*/*':`` part. -Start ``sinopia`` again: +Add the line and start ``sinopia`` again: ``` sinopia ``` -sinopia should tell you where the registry lives. Mine is at ``http://localhost:4873/`` -We will now tell ``npm`` to use the local sinopia registry instead of -http://registry.npmjs.com, as follows: +``sinopia`` should tell you where its registry lives. Mine is at +``http://localhost:4873/``. We will now tell ``npm`` to use the local +``sinopia`` registry instead of ``http://registry.npmjs.com``, as follows: ``` npm set registry http://localhost:4873 ``` @@ -73,11 +73,17 @@ cd ~/github/nlesc/ git clone https://github.com/NLeSC/create-react-app.git ``` -Next, we can publish any changes to the ``sinopia`` registry as follows: +Now, make the changes you want... ``` cd create-react-app/ +``` +...and publish them to the ``sinopia`` registry as follows: + +``` +# TODO you may need to have added an npm user to the repo for this next step +# to work. npm publish ``` From 9fcadb21690836c03b9ae9e74cf0b33b13fd1349 Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Tue, 8 Nov 2016 13:40:15 +0100 Subject: [PATCH 03/12] Some more textual changes --- development-setup.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/development-setup.md b/development-setup.md index 372cb7eca7a..a1af587b490 100644 --- a/development-setup.md +++ b/development-setup.md @@ -88,19 +88,19 @@ npm publish ``` Now when we want to test if the new version of ``create-react-app`` does what we -want it to do, we can ``cd`` to some other place, let's say ``~/tmp`` and run -``create-react-app`` there: +want it to do, we can ``cd`` to some other place, let's say ``~/tmp``: ``` cd ~/tmp ``` -npm install ``create-react-app`` locally: +``npm install`` ``create-react-app`` locally, using sinopia's repo: ``` npm install create-react-app ``` -The local install makes it a little easier to remove the ``node_modules`` -directory when additional changes have been made to ``create-react-app``, and -those changes have been ``npm publish``'ed to the sinopia repository. +The local install (``npm install`` with the ``-g`` flag) makes it a little +easier to remove the ``node_modules`` directory when additional changes have +been made to ``create-react-app``, and those changes have been +``npm publish``'ed to the sinopia repository. Now create a new app using the updated generator as follows: ``` From fd11106b5e9ac7d6fa273b0b4f0f77e05b77cbbe Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Tue, 8 Nov 2016 13:41:31 +0100 Subject: [PATCH 04/12] with -> without --- development-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-setup.md b/development-setup.md index a1af587b490..73bcbd535b2 100644 --- a/development-setup.md +++ b/development-setup.md @@ -97,7 +97,7 @@ cd ~/tmp ``` npm install create-react-app ``` -The local install (``npm install`` with the ``-g`` flag) makes it a little +The local install (``npm install`` without the ``-g`` flag) makes it a little easier to remove the ``node_modules`` directory when additional changes have been made to ``create-react-app``, and those changes have been ``npm publish``'ed to the sinopia repository. From 48322e528062c1e9dc4d2f6eb3f1fa0c9dc788d3 Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Tue, 8 Nov 2016 16:02:24 +0100 Subject: [PATCH 05/12] updated description of development setup --- development-setup.md | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/development-setup.md b/development-setup.md index 73bcbd535b2..8f79ef54e69 100644 --- a/development-setup.md +++ b/development-setup.md @@ -73,41 +73,53 @@ cd ~/github/nlesc/ git clone https://github.com/NLeSC/create-react-app.git ``` -Now, make the changes you want... +Any changes you make will likely be in one of ``create-react-app``'s consituent +packages, which are located at ``create-react-app/packages``. Each of its +subdirectories is a separate ``npm`` package. Let's say you want to make changes to +the App template from ``create-react-app/packages/react-scripts/template/src``. ``` -cd create-react-app/ +cd create-react-app/packages/react-scripts/template/src ``` -...and publish them to the ``sinopia`` registry as follows: +Now publish your changes to the ``sinopia`` registry as follows. Walk up the +directory tree until you find a ``package.json``. You should find one in ``create-react-app/packages/react-scripts/``. Look up the value for ``name``. +This will be the name the packaged is published under. For me, it's +``@nlesc/react-scripts``. Now publish the package to sinopia: + +TODO you may need to have added an npm user to the repo for this next step +to work. ``` -# TODO you may need to have added an npm user to the repo for this next step -# to work. npm publish ``` -Now when we want to test if the new version of ``create-react-app`` does what we -want it to do, we can ``cd`` to some other place, let's say ``~/tmp``: +Now when we want to test if the new version of ``@nlesc/react-scripts`` does +what we want it to do, we can ``cd`` to some other place, let's say ``~/tmp``: ``` cd ~/tmp ``` -``npm install`` ``create-react-app`` locally, using sinopia's repo: +``npm install`` ``@nlesc/react-scripts`` locally, using sinopia's repo: ``` -npm install create-react-app +npm install @nlesc/react-scripts ``` + +You can now inspect the package at ``~/tmp/node_modules/@nlesc/react-scripts/``. + The local install (``npm install`` without the ``-g`` flag) makes it a little easier to remove the ``node_modules`` directory when additional changes have -been made to ``create-react-app``, and those changes have been +been made to the package, and those changes have been ``npm publish``'ed to the sinopia repository. + Now create a new app using the updated generator as follows: ``` -cd ~/tmp -node_modules/.bin/create-react-app the-new-app +cd ~/tmp # or wherever you want the new app to be +create-react-app the-new-app --scripts-version @nlesc/react-scripts ``` - +This uses the globally installed ``create-react-app``, but with the custom +version of ``react-scripts``, namely @nlesc/react-scripts from sinopia. From 0fa48f278772c41133024eff7cc4e78091c6236a Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Wed, 9 Nov 2016 16:25:00 +0100 Subject: [PATCH 06/12] added tl;dr section stub --- development-setup.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/development-setup.md b/development-setup.md index 8f79ef54e69..3c86367b9fa 100644 --- a/development-setup.md +++ b/development-setup.md @@ -1,6 +1,14 @@ -# Description of the development setup for https://github.com/NLeSC/create-react-app +# Development setup for https://github.com/NLeSC/create-react-app +## TL;DR / long story short + +``` +TODO +``` + +## long story long + A user who just wants to automatically generate an initial setup for a React app could do so by installing the ``create-react-app`` generator as follows: ``` From 85b9783615c3f9b70ad6eecefa833fbb32ec2e66 Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Wed, 9 Nov 2016 17:07:31 +0100 Subject: [PATCH 07/12] added tldr section content --- development-setup.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/development-setup.md b/development-setup.md index 3c86367b9fa..c6405c12d41 100644 --- a/development-setup.md +++ b/development-setup.md @@ -1,12 +1,28 @@ -# Development setup for https://github.com/NLeSC/create-react-app +# Development setup +(for https://github.com/NLeSC/create-react-app) -## TL;DR / long story short + +## long story short ``` -TODO +npm install -g create-react-app +npm install -g verdaccio +verdaccio +npm set registry http://localhost:4873 +git clone https://github.com/NLeSC/create-react-app.git +cd create-react-app/packages/react-scripts + +npm version +npm adduser --registry http://localhost:4873/ +npm publish +cd +create-react-app my-app --scripts-version @nlesc/react-scripts + ``` + + ## long story long A user who just wants to automatically generate an initial setup for a React app From c2b782ae2ea45e342624b8d5964f85700741b396 Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Wed, 9 Nov 2016 17:08:39 +0100 Subject: [PATCH 08/12] - expanded the longer explanation part of the development setup; - added explanation of how to add a user to npm registry - some additional smaller corrections --- development-setup.md | 86 +++++++++++++++++++++++--------------------- 1 file changed, 46 insertions(+), 40 deletions(-) diff --git a/development-setup.md b/development-setup.md index c6405c12d41..aa607dbfa5c 100644 --- a/development-setup.md +++ b/development-setup.md @@ -41,53 +41,35 @@ This will create a directory ``your-app-name`` that contains a complete setup fo developing the newly created React app, including testing, code coverage generation, bundling, minification, incremental buidling, linting, etc. - Note that the above uses the ``npm`` registry at ``https://registry.npmjs.org/``. Now let's say you'd want to make changes to the template used to generate new apps, for example because you want new apps to be in TypeScript instead of the default JavaScript. For this, it is useful to run your own, local ``npm`` registry with hardly anything in it. You can do so with the following setup: -First ``npm install`` the package ``sinopia2``: +First ``npm install`` the package ``verdaccio``: ``` -npm installl -g sinopia2 +npm install -g verdaccio ``` Check to see if it works: ``` -sinopia -``` -Make a note of the name of the YAML config file. Mine is at -``~/.config/sinopia/config.yaml``. - -(Ctrl-C to end) - -Now edit the config file as follows. Near the bottom of the section marked -``packages`` there is a line: -``` -proxy:npmjs -``` -which is used for retrieving any packages missing from sinopia's ``npm`` registry. -Such packages are downloaded from the registry at ``https://registry.npmjs.org/`` -instead. - -However, note that there are two parts to the ``packages`` section. The proxy -line is in the ``'*':`` part. In order for proxying to work for scoped packages -as well as non-scoped packages, we need to add it to the ``'@*/*':`` part. - -Add the line and start ``sinopia`` again: -``` -sinopia +verdaccio ``` -``sinopia`` should tell you where its registry lives. Mine is at +``verdaccio`` should tell you where its registry lives. Mine is at ``http://localhost:4873/``. We will now tell ``npm`` to use the local -``sinopia`` registry instead of ``http://registry.npmjs.com``, as follows: +``verdaccio`` registry instead of ``http://registry.npmjs.com``, as follows: ``` npm set registry http://localhost:4873 ``` +If you want to return to the normal setup at a later point in time, you can do +so with: +``` +npm set registry https://registry.npmjs.com +``` Let's say you now want to make some changes to the ``create-react-app`` generator application. First get the source code of ``create-react-app`` using @@ -99,32 +81,56 @@ git clone https://github.com/NLeSC/create-react-app.git Any changes you make will likely be in one of ``create-react-app``'s consituent packages, which are located at ``create-react-app/packages``. Each of its -subdirectories is a separate ``npm`` package. Let's say you want to make changes to -the App template from ``create-react-app/packages/react-scripts/template/src``. +subdirectories is a separate ``npm`` package. Let's say you want to make changes +to the App template from ``create-react-app/packages/react-scripts/template/src``. ``` cd create-react-app/packages/react-scripts/template/src ``` -Now publish your changes to the ``sinopia`` registry as follows. Walk up the -directory tree until you find a ``package.json``. You should find one in ``create-react-app/packages/react-scripts/``. Look up the value for ``name``. -This will be the name the packaged is published under. For me, it's -``@nlesc/react-scripts``. Now publish the package to sinopia: +Before publishing your changes, you need to: +1. increment the semantic versioning of the package +1. add yourself as a user to verdaccio's npm registry server + +Let's first check what the current semantic version number is, as follows. Walk +up the directory tree until you find a ``package.json``. You should find one in +``create-react-app/packages/react-scripts/``. Look up the value for ``version``. +Now go back to the terminal and use ``npm version patch`` to increment the patch +part of the semantic version number. The 'patch' part of the +version value in package.json should have been incremented (reload your editor +if necessary). + +Now let's add a user to verdaccio, as follows: +``` +npm adduser --registry http://localhost:4873/ +``` +This will ask you to enter a user name, password, and e-mail address, which will +be stored in verdaccio. It doesn't really matter what you enter on any of the +three questions. + + +Now look up the value for ``name`` in package.json. This will be the name the +package is published under. For me, it's ``@nlesc/react-scripts``. + +Verify that verdaccio is the active npm registry with ``npm get registry``, and +that verdaccio is in fact up and running, then publish the package to verdaccio +with: -TODO you may need to have added an npm user to the repo for this next step -to work. ``` npm publish ``` +You can point your browser to http://localhost:4873/ to get an overview of +packages that are present in verdaccio's registry. + Now when we want to test if the new version of ``@nlesc/react-scripts`` does what we want it to do, we can ``cd`` to some other place, let's say ``~/tmp``: ``` cd ~/tmp ``` -``npm install`` ``@nlesc/react-scripts`` locally, using sinopia's repo: +``npm install`` ``@nlesc/react-scripts`` locally (still using verdaccio's repo): ``` npm install @nlesc/react-scripts ``` @@ -133,8 +139,8 @@ You can now inspect the package at ``~/tmp/node_modules/@nlesc/react-scripts/``. The local install (``npm install`` without the ``-g`` flag) makes it a little easier to remove the ``node_modules`` directory when additional changes have -been made to the package, and those changes have been -``npm publish``'ed to the sinopia repository. +been made to the package, and those changes have been ``npm publish``'ed to the +verdaccio registry. Now create a new app using the updated generator as follows: @@ -143,7 +149,7 @@ cd ~/tmp # or wherever you want the new app to be create-react-app the-new-app --scripts-version @nlesc/react-scripts ``` This uses the globally installed ``create-react-app``, but with the custom -version of ``react-scripts``, namely @nlesc/react-scripts from sinopia. +version of ``react-scripts``, namely ``@nlesc/react-scripts`` from verdaccio. From b1755ce0a541138b7360a6a2350305ef3cce5a5d Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Wed, 9 Nov 2016 17:13:30 +0100 Subject: [PATCH 09/12] Update development-setup.md --- development-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-setup.md b/development-setup.md index aa607dbfa5c..7de95378db0 100644 --- a/development-setup.md +++ b/development-setup.md @@ -73,7 +73,7 @@ npm set registry https://registry.npmjs.com Let's say you now want to make some changes to the ``create-react-app`` generator application. First get the source code of ``create-react-app`` using -nlesc's fork. I'm checking out the source code into ``~/github/nlesc/: +nlesc's fork. I'm checking out the source code into ``~/github/nlesc/``: ``` cd ~/github/nlesc/ git clone https://github.com/NLeSC/create-react-app.git From 0cf26e948348c896153e1c05b3b54fbbbd016779 Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Wed, 9 Nov 2016 17:14:02 +0100 Subject: [PATCH 10/12] Update development-setup.md --- development-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development-setup.md b/development-setup.md index 7de95378db0..cd9e55118ec 100644 --- a/development-setup.md +++ b/development-setup.md @@ -79,7 +79,7 @@ cd ~/github/nlesc/ git clone https://github.com/NLeSC/create-react-app.git ``` -Any changes you make will likely be in one of ``create-react-app``'s consituent +Any changes you make will likely be in one of ``create-react-app``'s constituent packages, which are located at ``create-react-app/packages``. Each of its subdirectories is a separate ``npm`` package. Let's say you want to make changes to the App template from ``create-react-app/packages/react-scripts/template/src``. From ede4c7daa5c20b7e7d5d8f64f56a28d30b670e49 Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Wed, 9 Nov 2016 17:15:46 +0100 Subject: [PATCH 11/12] Update development-setup.md --- development-setup.md | 1 + 1 file changed, 1 insertion(+) diff --git a/development-setup.md b/development-setup.md index cd9e55118ec..772330fc5e3 100644 --- a/development-setup.md +++ b/development-setup.md @@ -90,6 +90,7 @@ cd create-react-app/packages/react-scripts/template/src ``` Before publishing your changes, you need to: + 1. increment the semantic versioning of the package 1. add yourself as a user to verdaccio's npm registry server From c0ebc14eda5edde73bea977ef93947050fb04b3d Mon Sep 17 00:00:00 2001 From: "Jurriaan H. Spaaks" Date: Wed, 9 Nov 2016 17:42:39 +0100 Subject: [PATCH 12/12] Update development-setup.md --- development-setup.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/development-setup.md b/development-setup.md index 772330fc5e3..bccdf05b87f 100644 --- a/development-setup.md +++ b/development-setup.md @@ -44,10 +44,13 @@ bundling, minification, incremental buidling, linting, etc. Note that the above uses the ``npm`` registry at ``https://registry.npmjs.org/``. Now let's say you'd want to make changes to the template used to generate new apps, for example because you want new apps to be in TypeScript instead of the -default JavaScript. For this, it is useful to run your own, local ``npm`` registry -with hardly anything in it. You can do so with the following setup: +default JavaScript. For this, it is useful to run your own, local ``npm`` registry +using [verdaccio](https://github.com/verdaccio/verdaccio). Verdaccio sits between +you and https://registry.npmjs.com. It lets you publish development versions of +your npm package to the local, private repo, while still being able to retrieve +any other packages from the 'normal' registry at npmjs. -First ``npm install`` the package ``verdaccio``: +Install verdaccio with: ``` npm install -g verdaccio