feat: standalone examples (CodeSandbox) (#48)

* add codesandbox links to all examples, update template and example readme * control panel style fixes * add examples.css to published package * add exports to package.json
visgl · Nov 7, 2023 · 959c6e3 · 959c6e3
1 parent 69298c0
commit 959c6e3
Show file tree

Hide file tree

Showing 34 changed files with 696 additions and 222 deletions.
diff --git a/examples/README.md b/examples/README.md
@@ -19,8 +19,8 @@ additional scripts to start the example in the context of the library,
 using the library itself and its dependencies instead of those locally
 installed in the example folder.
 
-> In the future, we want to add codesandbox-links for all examples that
-> allow you to instantly start playing around with them.
+All examples should contain a link to a CodeSandbox environment where the
+example can be played with right away.
 
 ## Writing examples
 

diff --git a/examples/_template/README.md b/examples/_template/README.md
@@ -5,28 +5,34 @@
 This is an example to show how to setup a simple Google Maps Map with the `<Map/>` component of the Google Maps React
 library.
 
-## Instructions
+## Google Maps API key
+
+This example does not come with an API key. Running the examples locally requires a valid API key for the Google Maps Platform.
+See [the official documentation][get-api-key] on how to create and configure your own key.
+
+The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a
+file named `.env` in the example directory with the following content:
+
+```shell title=".env"
+GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
+```
+
+If you are on the CodeSandbox playground you can also choose to [provide the API key like this](https://codesandbox.io/docs/learn/environment/secrets)
+
+## Development
 
 Go into the example-directory and run
 
 ```shell
 npm install
 ```
 
-Then start the example with
+To start the example with the local library run
 
 ```shell
-npm start
+npm run start-local
 ```
 
-Running the examples locally requires a valid API key for the Google Maps Platform.
-See [the official documentation][get-api-key] on how to create and configure your own key.
-
-The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a
-file named `.env` in the example directory with the following content:
-
-```shell title=".env"
-GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
-```
+The regular `npm start` task is only used for the standalone versions of the example (CodeSandbox for example)
 
 [get-api-key]: https://developers.google.com/maps/documentation/javascript/get-api-key
diff --git a/examples/_template/index.html b/examples/_template/index.html
@@ -21,8 +21,9 @@
   <body>
     <div id="app"></div>
     <script type="module">
-      import '../../website/src/styles.css';
+      import '@vis.gl/react-google-maps/examples.css';
       import {renderToDom} from './src/app';
+
       renderToDom(document.querySelector('#app'));
     </script>
   </body>

diff --git a/examples/_template/package.json b/examples/_template/package.json
@@ -7,6 +7,7 @@
   },
   "scripts": {
     "start": "vite",
+    "start-local": "vite --config ../vite.config.local.js",
     "build": "vite build"
   }
 }
diff --git a/examples/_template/src/control-panel.tsx b/examples/_template/src/control-panel.tsx
@@ -7,7 +7,14 @@ function ControlPanel() {
       <p>
         Add a brief description of the example here and update the link below
       </p>
-      <div className="source-link">
+
+      <div className="links">
+        <a
+          href="https://codesandbox.io/s/github/visgl/react-google-maps/tree/main/examples/_template"
+          target="_new">
+          Try on CodeSandbox ↗
+        </a>
+
         <a
           href="https://github.com/visgl/react-google-maps/tree/main/examples/_template"
           target="_new">

diff --git a/examples/_template/vite.config.js b/examples/_template/vite.config.js
@@ -1,17 +1,11 @@
 import {defineConfig, loadEnv} from 'vite';
-import {resolve} from 'node:path';
 
 export default defineConfig(({mode}) => {
-  const {GOOGLE_MAPS_API_KEY} = loadEnv(mode, process.cwd(), '');
+  const {GOOGLE_MAPS_API_KEY = ''} = loadEnv(mode, process.cwd(), '');
 
   return {
     define: {
       'process.env.GOOGLE_MAPS_API_KEY': JSON.stringify(GOOGLE_MAPS_API_KEY)
-    },
-    resolve: {
-      alias: {
-        '@vis.gl/react-google-maps': resolve('../../src/index.ts')
-      }
     }
   };
 });
diff --git a/examples/basic-map/README.md b/examples/basic-map/README.md
@@ -5,28 +5,34 @@
 This is an example to show how to setup a simple Google Maps Map with the `<Map/>` component of the Google Maps React
 library.
 
-## Instructions
+## Google Maps API key
+
+This example does not come with an API key. Running the examples locally requires a valid API key for the Google Maps Platform.
+See [the official documentation][get-api-key] on how to create and configure your own key.
+
+The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a
+file named `.env` in the example directory with the following content:
+
+```shell title=".env"
+GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
+```
+
+If you are on the CodeSandbox playground you can also choose to [provide the API key like this](https://codesandbox.io/docs/learn/environment/secrets)
+
+## Development
 
 Go into the example-directory and run
 
 ```shell
 npm install
 ```
 
-Then start the example with
+To start the example with the local library run
 
 ```shell
-npm start
+npm run start-local
 ```
 
-Running the examples locally requires a valid API key for the Google Maps Platform.
-See [the official documentation][get-api-key] on how to create and configure your own key.
-
-The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a
-file named `.env` in the example directory with the following content:
-
-```shell title=".env"
-GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
-```
+The regular `npm start` task is only used for the standalone versions of the example (CodeSandbox for example)
 
 [get-api-key]: https://developers.google.com/maps/documentation/javascript/get-api-key
diff --git a/examples/basic-map/index.html b/examples/basic-map/index.html
@@ -21,10 +21,11 @@
     </style>
   </head>
   <body>
-    <div id="app" style=""></div>
+    <div id="app"></div>
     <script type="module">
-      import '../../website/src/styles.css';
+      import '@vis.gl/react-google-maps/examples.css';
       import {renderToDom} from './src/app';
+
       renderToDom(document.querySelector('#app'));
     </script>
   </body>

diff --git a/examples/basic-map/package.json b/examples/basic-map/package.json
@@ -7,6 +7,7 @@
   },
   "scripts": {
     "start": "vite",
+    "start-local": "vite --config ../vite.config.local.js",
     "build": "vite build"
   }
 }
diff --git a/examples/basic-map/src/control-panel.tsx b/examples/basic-map/src/control-panel.tsx
@@ -8,7 +8,13 @@ function ControlPanel() {
         The simplest example possible, just rendering a google map with some
         settings adjusted.
       </p>
-      <div className="source-link">
+      <div className="links">
+        <a
+          href="https://codesandbox.io/s/github/visgl/react-google-maps/tree/main/examples/basic-map"
+          target="_new">
+          Try on CodeSandbox ↗
+        </a>
+
         <a
           href="https://github.com/visgl/react-google-maps/tree/main/examples/basic-map"
           target="_new">

diff --git a/examples/basic-map/vite.config.js b/examples/basic-map/vite.config.js
@@ -1,17 +1,11 @@
 import {defineConfig, loadEnv} from 'vite';
-import {resolve} from 'node:path';
 
 export default defineConfig(({mode}) => {
-  const {GOOGLE_MAPS_API_KEY} = loadEnv(mode, process.cwd(), '');
+  const {GOOGLE_MAPS_API_KEY = ''} = loadEnv(mode, process.cwd(), '');
 
   return {
     define: {
       'process.env.GOOGLE_MAPS_API_KEY': JSON.stringify(GOOGLE_MAPS_API_KEY)
-    },
-    resolve: {
-      alias: {
-        '@vis.gl/react-google-maps': resolve('../../src/index.ts')
-      }
     }
   };
 });
diff --git a/examples/change-map-id/README.md b/examples/change-map-id/README.md
@@ -2,31 +2,37 @@
 
 ![image](https://user-images.githubusercontent.com/39244966/208682692-d5b23518-9e51-4a87-8121-29f71e41c777.png)
 
-This is an example to show how to setup a simple Google Maps Map with the `<Map/>` component of the Google Maps React
+This is an example to show how to change the map id of a simple Google Maps Map with the `<Map/>` component of the Google Maps React
 library.
 
-## Instructions
+## Google Maps API key
+
+This example does not come with an API key. Running the examples locally requires a valid API key for the Google Maps Platform.
+See [the official documentation][get-api-key] on how to create and configure your own key.
+
+The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a
+file named `.env` in the example directory with the following content:
+
+```shell title=".env"
+GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
+```
+
+If you are on the CodeSandbox playground you can also choose to [provide the API key like this](https://codesandbox.io/docs/learn/environment/secrets)
+
+## Development
 
 Go into the example-directory and run
 
 ```shell
 npm install
 ```
 
-Then start the example with
+To start the example with the local library run
 
 ```shell
-npm start
+npm run start-local
 ```
 
-Running the examples locally requires a valid API key for the Google Maps Platform.
-See [the official documentation][get-api-key] on how to create and configure your own key.
-
-The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a
-file named `.env` in the example directory with the following content:
-
-```shell title=".env"
-GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
-```
+The regular `npm start` task is only used for the standalone versions of the example (CodeSandbox for example)
 
 [get-api-key]: https://developers.google.com/maps/documentation/javascript/get-api-key
diff --git a/examples/change-map-id/index.html b/examples/change-map-id/index.html
@@ -21,7 +21,7 @@
   <body>
     <div id="app"></div>
     <script type="module">
-      import '../../website/src/styles.css';
+      import '@vis.gl/react-google-maps/examples.css';
       import {renderToDom} from './src/app';
 
       renderToDom(document.querySelector('#app'));

diff --git a/examples/change-map-id/package.json b/examples/change-map-id/package.json
@@ -7,6 +7,7 @@
   },
   "scripts": {
     "start": "vite",
+    "start-local": "vite --config ../vite.config.local.js",
     "build": "vite build"
   }
 }
diff --git a/examples/change-map-id/src/app.tsx b/examples/change-map-id/src/app.tsx
@@ -10,8 +10,6 @@ import {
 } from '@vis.gl/react-google-maps';
 import ControlPanel from './control-panel';
 
-const API_KEY = process.env.GOOGLE_MAPS_API_KEY as string;
-
 const MapTypeId = {
   HYBRID: 'hybrid',
   ROADMAP: 'roadmap',
@@ -73,6 +71,8 @@ const MAP_CONFIGS: MapConfig[] = [
   }
 ];
 
+const API_KEY = process.env.GOOGLE_MAPS_API_KEY as string;
+
 const App = () => {
   const [mapConfig, setMapConfig] = useState<MapConfig>(MAP_CONFIGS[0]);
   const [infowindowOpen, setInfowindowOpen] = useState(true);

diff --git a/examples/change-map-id/src/control-panel.tsx b/examples/change-map-id/src/control-panel.tsx
@@ -38,7 +38,13 @@ function ControlPanel({
         </select>
       </div>
 
-      <div className="source-link">
+      <div className="links">
+        <a
+          href="https://codesandbox.io/s/github/visgl/react-google-maps/tree/main/examples/change-map-id"
+          target="_new">
+          Try on CodeSandbox ↗
+        </a>
+
         <a
           href="https://github.com/visgl/react-google-maps/tree/main/examples/change-map-id"
           target="_new">

diff --git a/examples/change-map-id/vite.config.js b/examples/change-map-id/vite.config.js
@@ -1,17 +1,11 @@
 import {defineConfig, loadEnv} from 'vite';
-import {resolve} from 'node:path';
 
 export default defineConfig(({mode}) => {
-  const {GOOGLE_MAPS_API_KEY} = loadEnv(mode, process.cwd(), '');
+  const {GOOGLE_MAPS_API_KEY = ''} = loadEnv(mode, process.cwd(), '');
 
   return {
     define: {
       'process.env.GOOGLE_MAPS_API_KEY': JSON.stringify(GOOGLE_MAPS_API_KEY)
-    },
-    resolve: {
-      alias: {
-        '@vis.gl/react-google-maps': resolve('../../src/index.ts')
-      }
     }
   };
 });
diff --git a/examples/deckgl-overlay/README.md b/examples/deckgl-overlay/README.md
@@ -5,28 +5,34 @@ to a `<Map>` component. (using the `GoogleMapsOverlay` from [@deck.gl/google-map
 
 [@deck.gl/google-maps]: https://deck.gl/docs/api-reference/google-maps/overview
 
-## Instructions
+## Google Maps API key
+
+This example does not come with an API key. Running the examples locally requires a valid API key for the Google Maps Platform.
+See [the official documentation][get-api-key] on how to create and configure your own key.
+
+The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a
+file named `.env` in the example directory with the following content:
+
+```shell title=".env"
+GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
+```
+
+If you are on the CodeSandbox playground you can also choose to [provide the API key like this](https://codesandbox.io/docs/learn/environment/secrets)
+
+## Development
 
 Go into the example-directory and run
 
 ```shell
 npm install
 ```
 
-Then start the example with
+To start the example with the local library run
 
 ```shell
-npm start
+npm run start-local
 ```
 
-Running the examples locally requires a valid API key for the Google Maps Platform.
-See [the official documentation][get-api-key] on how to create and configure your own key.
-
-The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a
-file named `.env` in the example directory with the following content:
-
-```shell title=".env"
-GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
-```
+The regular `npm start` task is only used for the standalone versions of the example (CodeSandbox for example)
 
 [get-api-key]: https://developers.google.com/maps/documentation/javascript/get-api-key
diff --git a/examples/deckgl-overlay/index.html b/examples/deckgl-overlay/index.html
@@ -21,8 +21,9 @@
   <body>
     <div id="app"></div>
     <script type="module">
-      import '../../website/src/styles.css';
+      import '@vis.gl/react-google-maps/examples.css';
       import {renderToDom} from './src/app';
+
       renderToDom(document.querySelector('#app'));
     </script>
   </body>