Esri · gavinr-maps · Jan 10, 2025 · Jan 3, 2025 · Jan 3, 2025 · Jan 3, 2025
diff --git a/README.md b/README.md
@@ -1 +1,60 @@
 # ArcGIS REST JS Samples
+
+This repository contains a variety of samples of different ways to use [ArcGIS REST JS](https://github.com/Esri/arcgis-rest-js). Please see the [samples folder](samples/) for the entire list. Each sample has a README file to explain how to run the sample.
+
+## Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS while running one of the samples, follow these steps.
+
+### Local ArcGIS REST JS (NPM)
+
+For samples that use NPM to install ArcGIS REST JS as a dependency, follow these steps.
+
+1. In the ArcGIS REST JS directory, run these commands:
+
+   ```bash
+   npm install
+   npm run build
+   ```
+
+2. In this sample's directory, run these commands,
+
+   1. Replacing `..\..\path\to` with the path to where you have ArcGIS REST JS stored, and
+   2. Using the associated package folder(s) that are being used by the current sample (e.g. `packages\arcgis-rest-feature-service`, `packages\arcgis-rest-geocoding`, etc.)
+
+   ```bash
+   npm install
+   npm link ..\..\path\to\arcgis-rest-js\packages\arcgis-rest-feature-service\
+   ```
+
+Remember that you must run `npm run build` in the ArcGIS REST JS repository after making changes to see those changes when running the sample.
+
+To remove the link and use the package from NPM instead of the local one, run `npm install` in the sample folder again.
+
+### Local ArcGIS REST JS (Browser)
+
+For samples that use a `<script>` tag to reference ArcGIS REST JS in the browser, follow these steps.
+
+1. In the ArcGIS REST JS directory, run these commands. This will run a local server hosting ArcGIS REST JS.
+
+   ```bash
+   npm install
+   npm run build
+   node .\scripts\run-demo-server.js
+   ```
+
+2. In this sample's directory, in the HTML file code, change the `<script>` tag(s) from `https://unpkg.com` to `https://localhost:8080` (or whatever port is used in step 1). For example, change this:
+
+   ```html
+   <script src="https://unpkg.com/@esri/arcgis-rest-feature-service/dist/bundled/feature-service.umd.js"></script>
+   ```
+
+   ... to this:
+
+   ```html
+   <script src="https://localhost:8080/@esri/arcgis-rest-feature-service/dist/bundled/feature-service.umd.js"></script>
+   ```
+
+## Sample Repository Maintenance
+
+In order to not need to constantly update the packages, we are not including `package-lock.json` files within samples the use NPM to install dependencies. See [.gitignore](.gitignore).
diff --git a/samples/attachments-browser/README.md b/samples/attachments-browser/README.md
@@ -1,7 +1,15 @@
-# Running this demo
+# Attachments Browser
 
-1. Make sure you run `npm run build` in the root folder to setup the dependencies
-1. `npm start`
-1. Visit http://localhost:8080
+## Running this sample
 
-**Note:** The server starts with a special configuration to serve URLs starting with `@esri/arcgis-rest-*` from their respective packages. In your application you will need to change these URLs to point to their respective locations.
+For this sample, you do not need to install any dependencies - it uses ArcGIS REST JS from the Unpkg CDN. To run this sample, you just need to host the `index.html` file. There are a variety of ways to do that; one simple way is to use the [serve](https://www.npmjs.com/package/serve) package:
+
+```bash
+npx serve
+```
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow the [steps in the parent README](../README.md#local-arcgis-rest-js-browser), updating the script tags in these files as necessary:
+
+- `index.html`
diff --git a/samples/attachments-browser/index.html b/samples/attachments-browser/index.html
@@ -1,8 +1,15 @@
 <!DOCTYPE html>
 <html>
-<title>Attachments</title>
+  <head>
 
-<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
+    <title>Attachments</title>
+
+    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
+
+    <script src="https://rawgit.com/kriszyp/put-selector/master/put.js"></script>
+    <script src="https://unpkg.com/@esri/arcgis-rest-request/dist/bundled/request.umd.js"></script>
+    <script src="https://unpkg.com/@esri/arcgis-rest-feature-service/dist/bundled/feature-service.umd.js"></script>
+  </head>
 
 <div class="container-fluid">
   <div class="row">
@@ -15,7 +22,7 @@ <h3>Attachments</h3>
         </div>
         <div class="form-group">
           <label for="featureId">Feature ID</label>
-          <input type="number" min="0" step="1" id="featureId" name="featureId" class="form-control" value="8254973" required>
+          <input type="number" min="0" step="1" id="featureId" name="featureId" class="form-control" value="21502403" required>
         </div>
         <div class="form-group">
           <button type="submit" class="btn"><span class="glyphicon glyphicon-paperclip" aria-hidden="true"></span> Get Attachments</button>
@@ -53,10 +60,6 @@ <h3>Attachments</h3>
   </div>
 </div>
 
-<script src="https://rawgit.com/kriszyp/put-selector/master/put.js"></script>
-<script src="@esri/arcgis-rest-request/dist/bundled/request.umd.js"></script>
-<script src="@esri/arcgis-rest-feature-service/dist/bundled/feature-service.umd.js"></script>
-
 <script>
   let serviceUrl, featureId;
 

diff --git a/samples/attachments-browser/package.json b/samples/attachments-browser/package.json
diff --git a/samples/attachments-node/README.md b/samples/attachments-node/README.md
@@ -1,4 +1,13 @@
 # Native JavaScript Modules in Node.js
 
-1. Run `npm run build` in the root directory
-1. Run `npm start` to make a require and log output.
+## Running this sample
+
+1. Run `npm install` to install the dependencies.
+2. Run `npm start` to make a require and log output.
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow the [steps in the parent README](../README.md#local-arcgis-rest-js-npm), referencing these packages that this sample uses as necessary:
+
+- `arcgis-rest-request`
+- `arcgis-rest-feature-service`
diff --git a/samples/attachments-node/package.json b/samples/attachments-node/package.json
@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@esri/arcgis-rest-request": "^4.0.0",
+    "@esri/arcgis-rest-feature-service": "^4.0.0",
     "fetch-blob": "^3.1.2",
     "mime": "^2.5.2",
     "mime-types": "^2.1.32"

diff --git a/samples/batch-geocoder-node/README.md b/samples/batch-geocoder-node/README.md
@@ -1,6 +1,8 @@
-# Running this demo
+# Batch Geocoder (Node)
 
-1. Make sure you run `npm run build` in the root folder to setup the dependencies
+## Running this sample
+
+1. run `npm install` to install the dependencies.
 2. Create and register a [new application](https://developers.arcgis.com/documentation/core-concepts/security-and-authentication/accessing-arcgis-online-services/).
 3. Replace values in [config-template.js](/demos/batch-geocoder-node/config-template.js) and rename to `config.js`
    1. `"clientId"`: ArcGIS ClientId
@@ -11,3 +13,10 @@
 4. `npm start`
 
 Sample Restaurant Inspections adapted from a DOHMH dataset available [online](https://data.cityofnewyork.us/Health/DOHMH-New-York-City-Restaurant-Inspection-Results/xx67-kt59/data)
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow the [steps in the parent README](../README.md#local-arcgis-rest-js-npm), referencing these packages that this sample uses as necessary:
+
+- `arcgis-rest-request`
+- `arcgis-rest-geocoding`
diff --git a/samples/browser-es-modules/README.md b/samples/browser-es-modules/README.md
@@ -1,7 +1,15 @@
 # ArcGIS REST JS + Native Browser Modules
 
-1. Run `npm run build` in the root directory
-1. Run `npm start` to spin up the development server.
-1. Visit [http://localhost:8080](http://localhost:8080).
+## Running this sample
 
-**Note:** The server starts with a special configuration to serve URLs starting with `@esri/arcgis-rest-*` from their respective packages. In your application you will need to change these URLs to point to their respective locations.
+For this sample, you do not need to install any dependencies - it uses ArcGIS REST JS from the Unpkg CDN. To run this sample, you just need to host the `index.html` file. There are a variety of ways to do that; one simple way is to use the [serve](https://www.npmjs.com/package/serve) package:
+
+```bash
+npx serve
+```
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow the [steps in the parent README](../README.md#local-arcgis-rest-js-browser), updating the script tags in these files as necessary:
+
+- `index.html`
diff --git a/samples/browser-es-modules/index.html b/samples/browser-es-modules/index.html
@@ -1,38 +1,42 @@
 <!DOCTYPE html>
 <html lang="en">
-
-<head>
-  <meta charset="utf-8">
-  <title>ArcGIS REST JS Browser w/ Modules</title>
-  <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
-    integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
-
-</head>
-
-<body>
-  <!-- Load the ES Modules Polyfill so we can use importmap in FF and Safari -->
-  <script async src="https://unpkg.com/[email protected]/dist/es-module-shims.js"></script>
-
-  <!-- Map package imports to URLS starting with @esri/... which will get served from the local build of the modules -->
-  <script type="importmap">
-  {
-    "imports": {
-      "@esri/arcgis-rest-request": "/@esri/arcgis-rest-request/dist/bundled/request.esm.js",
-      "@esri/arcgis-rest-portal": "/@esri/arcgis-rest-portal/dist/bundled/portal.esm.js"
-    }
-  }
-  </script>
-
-  <script type="module">
-    import { searchItems } from "@esri/arcgis-rest-portal";
-
-    let element = document.createElement("pre");
-    document.body.appendChild(element);
-
-    searchItems("water").then((response) => {
-      element.textContent = JSON.stringify(response, null, 2); // false
-    });
-  </script>
-</body>
-
-</html>
+  <head>
+    <meta charset="utf-8" />
+    <title>ArcGIS REST JS Browser w/ Modules</title>
+    <link
+      rel="stylesheet"
+      href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
+      integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u"
+      crossorigin="anonymous"
+    />
+  </head>
+
+  <body>
+    <!-- Load the ES Modules Polyfill so we can use importmap in FF and Safari -->
+    <script
+      async
+      src="https://unpkg.com/[email protected]/dist/es-module-shims.js"
+    ></script>
+
+    <!-- Map package imports to URLS starting with @esri/... which will get served from the local build of the modules -->
+    <script type="importmap">
+      {
+        "imports": {
+          "@esri/arcgis-rest-request": "https://unpkg.com/@esri/arcgis-rest-request/dist/bundled/request.esm.js",
+          "@esri/arcgis-rest-portal": "https://unpkg.com/@esri/arcgis-rest-portal/dist/bundled/portal.esm.js"
+        }
+      }
+    </script>
+
+    <script type="module">
+      import { searchItems } from "@esri/arcgis-rest-portal";
+
+      let element = document.createElement("pre");
+      document.body.appendChild(element);
+
+      searchItems("water").then((response) => {
+        element.textContent = JSON.stringify(response, null, 2); // false
+      });
+    </script>
+  </body>
+</html>
diff --git a/samples/browser-es-modules/package.json b/samples/browser-es-modules/package.json
diff --git a/samples/deno/README.md b/samples/deno/README.md
@@ -1,9 +1,33 @@
 # ArcGIS REST JS + Deno
 
-ArcGIS REST JS is fully compatible with Deno. You can import the packages from the [esm.run CDN](https://www.jsdelivr.com/esm) for the easiest use. This demo shows importing from a local install with an import map.
+## Running this sample
 
-You can run this demo with:
+ArcGIS REST JS is fully compatible with Deno. You can run this demo with:
 
 ```
-deno run --allow-net --import-map ./import_map.json index.js
+deno run --allow-net --allow-import --import-map ./import_map.json index.js
+```
+
+### Local ArcGIS REST JS
+
+If you'd like to use a local version of ArcGIS REST JS, follow these steps.
+
+1. In the ArcGIS REST JS directory, run these commands. This will run a local server hosting ArcGIS REST JS.
+
+```bash
+npm install
+npm run build
+node .\scripts\run-demo-server.js
+```
+
+2. In this sample's directory, update `import_map.json` with relative paths to the files on your computer. For example replace this:
+
+```json
+"https://esm.run/@esri/arcgis-rest-form-data/browser-ponyfill.mjs"
+```
+
+... with this:
+
+```json
+"../../path/to/arcgis-rest-js/packages/arcgis-rest-form-data/browser-ponyfill.mjs"
 ```
diff --git a/samples/deno/import_map.json b/samples/deno/import_map.json
@@ -1,8 +1,8 @@
-  {
-    "imports": {
-      "@esri/arcgis-rest-form-data": "../../packages/arcgis-rest-form-data/browser-ponyfill.mjs",
-      "@esri/arcgis-rest-fetch": "../../packages/arcgis-rest-fetch/browser-ponyfill.mjs",
-      "@esri/arcgis-rest-request": "../../packages/arcgis-rest-request/dist/esm/index.js",
-      "@esri/arcgis-rest-portal": "../../packages/arcgis-rest-portal/dist/esm/index.js"
-    }
-  }
+{
+  "imports": {
+    "@esri/arcgis-rest-form-data": "https://esm.run/@esri/arcgis-rest-form-data/browser-ponyfill.mjs",
+    "@esri/arcgis-rest-fetch": "https://esm.run/@esri/arcgis-rest-fetch/browser-ponyfill.mjs",
+    "@esri/arcgis-rest-request": "https://esm.run/@esri/arcgis-rest-request/dist/esm/index.js",
+    "@esri/arcgis-rest-portal": "https://esm.run/@esri/arcgis-rest-portal/dist/esm/index.js"
+  }
+}