examples: add npm run example script

a bad result from adding the examples as dependencies of the root
repository is that they now don't have access to the npm binaries they
need to run in their own folder, because they are installed into the
root repository instead.

this works around that issue.

we may need to consider undoing that change and making the examples work
as standalone projects again, that's easier to understand.

fixes #2024 for now.

bin/run-example.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+/**
+ * Lerna installs all the example dependencies into the root `node_modules`.
+ * To run the examples they need to have access to executables from npm dependencies in their $PATH.
+ * If you run `npm start` in a dependency folder, the root `node_modules/.bin` is not in the $PATH.
+ *
+ * This proxy executable can be run from the repository root using `npm run example`, so the root
+ * `node_modules/.bin` will be in the $PATH. It then runs `npm start` in the specific example folder,
+ * which will inherit the $PATH, so the example has access to executables from npm dependencies in both
+ * its own and in the root `node_modules`.
+ */
+
+const path = require('path')
+const { execSync } = require('child_process')
+const exampleName = process.argv[2]
+
+if (!exampleName) {
+  console.error('Usage: npm run example "name-of-example"')
+  process.exit(1)
+}
+
+const exampleDir = path.join(__dirname, '../examples', exampleName)
+const pkg = require(path.join(exampleDir, 'package.json'))
+if (pkg.scripts && pkg.scripts.build) {
+  execSync('npm run build', { cwd: exampleDir, stdio: 'inherit' })
+}
+
+execSync('npm start', { cwd: exampleDir, stdio: 'inherit' })

examples/aws-companion/readme.md

@@ -5,17 +5,15 @@ Files are uploaded to a randomly named directory inside the `whatever/` director
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
-npm run build
 ```
+That will also install the dependencies for this example.
 
 Then, set up the `COMPANION_AWS_KEY`, `COMPANION_AWS_SECRET`, `COMPANION_AWS_REGION`, and `COMPANION_AWS_BUCKET` environment variables for @uppy/companion.
 
-Then, navigate to this directory and run:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example aws-companion
 ```

examples/aws-presigned-url/readme.md

@@ -4,14 +4,14 @@ This example uses a server-side PHP endpoint to sign uploads to S3.
 
 ## Running It
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
 ```
+That will also install the npm dependencies for this example.
 
-This example uses the AWS PHP SDK.
-To install it, [get composer](https://getcomposer.org) and run `composer update` in this folder.
+This example also uses the AWS PHP SDK.
+To install it, [get composer](https://getcomposer.org) and run `composer update` in **this** folder.
 
 ```bash
 cd ./examples/aws-presigned-url
@@ -21,16 +21,13 @@ composer update
 Configure AWS S3 credentials using [environment variables](https://docs.aws.amazon.com/aws-sdk-php/v3/guide/guide/credentials.html#environment-credentials) or a [credentials file in `~/.aws/credentials`](https://docs.aws.amazon.com/aws-sdk-php/v3/guide/guide/credentials.html#credential-profiles).
 Configure a bucket name and region in the `s3-sign.php` file.
 
-Then start the demo server using:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example aws-presigned-url
 ```
-
 The demo should now be available at http://localhost:8080.
 
 Optionally, provide a port in the `PORT` environment variable:
-
 ```bash
-PORT=8080 npm start
+PORT=8080 npm run example aws-presigned-url
 ```

examples/custom-provider/readme.md

@@ -5,14 +5,13 @@ This serves as an illustration on how integrating custom providers would work
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
 ```
+That will also install the dependencies for this example.
 
-Move into this directory, then:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example custom-provider
 ```

examples/digitalocean-spaces/readme.md

@@ -2,18 +2,19 @@
 
 This example uses Uppy to upload files to a DigitolOcean Space. DigitalOcean Spaces has an identical API to S3, so we can use the [AwsS3](https://uppy.io/docs/aws-s3) plugin. We use @uppy/companion with a [custom `endpoint` configuration](./server.js#L32-L33) that points to DigitalOcean.
 
-To run this example, make sure you've correctly installed the root repository:
+## Running it
 
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
 ```
+That will also install the dependencies for this example.
 
-Then navigate to this directory, configure some environment variables, and run:
-
+Then, again in the **repository root**, configure some environment variables, and run:
 ```bash
 COMPANION_AWS_REGION=ams3 \
 COMPANION_AWS_KEY=your_access_key_id \
 COMPANION_AWS_SECRET=your_secret_access_key \
 COMPANION_AWS_BUCKET=your_space_name \
-npm start
+npm run example digitalocean-spaces
 ```

examples/multiple-instances/readme.md

@@ -1,18 +1,17 @@
 # Multiple Instances
 
-This example uses Uppy with the RestoreFiles plugin.
+This example uses Uppy with the `@uppy/golden-retriever` plugin.
 It has two instances on the same page, side-by-side, but with different `id`s so their stored files don't interfere with each other.
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
 ```
+That will also install the dependencies for this example.
 
-Move into this directory, then:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example multiple-instances
 ```

examples/node-xhr/readme.md

@@ -4,14 +4,13 @@ This example uses Node server and `@uppy/xhr-upload` to upload files to the loca
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
 ```
+That will also install the dependencies for this example.
 
-Then move into this directory (`examples/node-xhr`), and:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example node-xhr
 ```

examples/php-xhr/readme.md

@@ -4,15 +4,13 @@ This example uses PHP server and `@uppy/xhr-upload` to upload files to the local
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
-npm run build
 ```
+That will also install the dependencies for this example.
 
-Then move into this directory (`examples/php-xhr`), and:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example php-xhr
 ```

examples/python-xhr/readme.md

@@ -4,16 +4,19 @@ This example uses a Python Flask server and `@uppy/xhr-upload` to upload files t
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
-npm run build
 ```
+That will also install the npm dependencies for this example.
 
-Then move into this directory (`examples/python-xhr`), and:
-
+Additionally, this example uses python dependencies. Move into this directory, and install them using pip:
 ```bash
+cd ./examples/python-xhr
 pip install -r requirements.txt
-npm start
+```
+
+Then, again in the **repository root**, start this example by doing:
+```bash
+npm run example python-xhr
 ```

examples/react-native-expo/readme.md

@@ -6,18 +6,15 @@
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
-npm run build
 ```
+That will also install the dependencies for this example.
 
-Then navigate to this directory and run it:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-cd examples/react-native-expo
-npm start
+npm run example react-native-expo
 ```
 
 Then a tab will open in your browser with Expo UI, and you can choose to run the example in either an iOS or Android simulator, or right on your mobile device with an Expo app — might be easier, if you don’t want to install emulators.

examples/redux/readme.md

@@ -8,14 +8,13 @@ This example supports the [Redux Devtools extension](https://github.com/zalmoxis
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
 ```
+That will also install the dependencies for this example.
 
-Move into this directory, then:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example redux
 ```

examples/transloadit/readme.md

@@ -4,14 +4,13 @@ This example shows all the different Robodog APIs in action on a single page.
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
 ```
+That will also install the dependencies for this example.
 
-Move into this directory, then:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example transloadit
 ```

examples/uppy-with-companion/README.md

@@ -4,14 +4,13 @@ This is a simple, lean example that combines the usage of @uppy/companion and up
 
 ## Test it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
 ```
+That will also install the dependencies for this example.
 
-Then, navigate to this directory and run:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example uppy-with-companion
 ```

examples/xhr-bundle/readme.md

@@ -6,14 +6,13 @@ This example uses Uppy with XHRUpload plugin in `bundle` mode. Bundle mode uploa
 
 ## Run it
 
-To run this example, make sure you've correctly installed the root repository:
-
+To run this example, make sure you've correctly installed the **repository root**:
 ```bash
 npm install
 ```
+That will also install the dependencies for this example.
 
-Move into this directory, then:
-
+Then, again in the **repository root**, start this example by doing:
 ```bash
-npm start
+npm run example xhr-bundle
 ```