feat: standalone examples (CodeSandbox)

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
 

examples/_template/README.md

@@ -13,12 +13,14 @@ Go into the example-directory and run
 npm install
 ```
 
-Then start the example with
+To start the example with the local library run
 
 ```shell
-npm start
+npm run start-local
 ```
 
+The regular `npm start` task is only used for the standalone versions of the the example (CodeSandbox for example)
+
 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.
 

examples/_template/package.json

@@ -7,6 +7,7 @@
   },
   "scripts": {
     "start": "vite",
+    "start-local": "vite --config ../vite.config.local.js",
     "build": "vite build"
   }
 }

examples/_template/src/app.tsx

@@ -3,7 +3,9 @@ import {createRoot} from 'react-dom/client';
 
 import {APIProvider, Map} from '@vis.gl/react-google-maps';
 
-const API_KEY = process.env.GOOGLE_MAPS_API_KEY as string;
+import {getApiKey} from './lib/get-api-key';
+
+const API_KEY = getApiKey();
 
 const App = () => <APIProvider apiKey={API_KEY}></APIProvider>;
 

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">

examples/_template/src/lib/get-api-key.ts

@@ -0,0 +1,20 @@
+export function getApiKey() {
+  const url = new URL(location.href);
+  const apiKey =
+    url.searchParams.get('apiKey') ||
+    (process.env.GOOGLE_MAPS_API_KEY as string);
+
+  if (!apiKey) {
+    const key = prompt(
+      'Please provide your Google Maps API key in the URL\n' +
+        '(using the parameter `?apiKey=YOUR_API_KEY_HERE`) or enter it here:'
+    );
+
+    if (key) {
+      url.searchParams.set('apiKey', key);
+      location.replace(url.toString());
+    }
+  }
+
+  return apiKey;
+}

examples/_template/src/styles.css

@@ -0,0 +1,37 @@
+.control-panel {
+  font-size: 14px;
+  line-height: 18px;
+  width: 284px;
+  background: #fff;
+  box-shadow: 0 0 4px rgba(0, 0, 0, 0.15);
+  margin: 24px;
+  padding: 12px 24px;
+  position: absolute;
+  top: 0;
+  right: 0;
+  outline: none;
+  cursor: auto;
+  box-sizing: border-box;
+
+  & h3 {
+    font-size: 1.2em;
+    font-weight: 500;
+    margin: 8px 0;
+  }
+
+  & p {
+    margin-bottom: 16px;
+  }
+
+  .links {
+    margin-top: 8px;
+    display: flex;
+    justify-content: space-between;
+
+    & a {
+      font-weight: bold;
+      color: #486865;
+      font-size: 11px;
+    }
+  }
+}

examples/_template/vite.config.js

@@ -1,17 +1,7 @@
-import {defineConfig, loadEnv} from 'vite';
-import {resolve} from 'node:path';
-
-export default defineConfig(({mode}) => {
-  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')
-      }
-    }
-  };
-});
+export default {
+  define: {
+    'process.env.GOOGLE_MAPS_API_KEY': JSON.stringify(
+      process.env.GOOGLE_MAPS_API_KEY
+    )
+  }
+};

examples/basic-map/README.md

@@ -13,12 +13,14 @@ Go into the example-directory and run
 npm install
 ```
 
-Then start the example with
+To start the example with the local library run
 
 ```shell
-npm start
+npm run start-local
 ```
 
+The regular `npm start` task is only used for the standalone versions of the the example (CodeSandbox for example)
+
 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.
 

examples/basic-map/index.html

@@ -21,9 +21,9 @@
     </style>
   </head>
   <body>
-    <div id="app" style=""></div>
+    <div id="app"></div>
     <script type="module">
-      import '../../website/src/styles.css';
+      import './src/styles.css';
       import {renderToDom} from './src/app';
       renderToDom(document.querySelector('#app'));
     </script>

examples/basic-map/package.json

@@ -7,6 +7,7 @@
   },
   "scripts": {
     "start": "vite",
+    "start-local": "vite --config ../vite.config.local.js",
     "build": "vite build"
   }
 }

examples/basic-map/src/app.tsx

@@ -4,10 +4,10 @@ import {createRoot} from 'react-dom/client';
 import {APIProvider, Map} from '@vis.gl/react-google-maps';
 import ControlPanel from './control-panel';
 
-const API_KEY = process.env.GOOGLE_MAPS_API_KEY as string;
+import {getApiKey} from './lib/get-api-key';
 
 const App = () => (
-  <APIProvider apiKey={API_KEY}>
+  <APIProvider apiKey={getApiKey()}>
     <Map
       zoom={3}
       center={{lat: 22.54992, lng: 0}}

examples/basic-map/src/control-panel.tsx

@@ -2,13 +2,19 @@ import * as React from 'react';
 
 function ControlPanel() {
   return (
-    <div className="control-panel">
+    <div className="control-panel-basic-map">
       <h3>Basic Map</h3>
       <p>
         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">

examples/basic-map/src/lib/get-api-key.ts

@@ -0,0 +1,20 @@
+export function getApiKey() {
+  const url = new URL(location.href);
+  const apiKey =
+    url.searchParams.get('apiKey') ||
+    (process.env.GOOGLE_MAPS_API_KEY as string);
+
+  if (!apiKey) {
+    const key = prompt(
+      'Please provide your Google Maps API key in the URL\n' +
+        '(using the parameter `?apiKey=YOUR_API_KEY_HERE`) or enter it here:'
+    );
+
+    if (key) {
+      url.searchParams.set('apiKey', key);
+      location.replace(url.toString());
+    }
+  }
+
+  return apiKey;
+}

examples/basic-map/src/styles.css

@@ -0,0 +1,37 @@
+.control-panel-basic-map {
+  font-size: 14px;
+  line-height: 18px;
+  width: 284px;
+  background: #fff;
+  box-shadow: 0 0 4px rgba(0, 0, 0, 0.15);
+  margin: 24px;
+  padding: 12px 24px;
+  position: absolute;
+  top: 0;
+  right: 0;
+  outline: none;
+  cursor: auto;
+  box-sizing: border-box;
+}
+
+.control-panel-basic-map h3 {
+  font-size: 1.2em;
+  font-weight: 500;
+  margin: 8px 0;
+}
+
+.control-panel-basic-map p {
+  margin-bottom: 16px;
+}
+
+.control-panel-basic-map .links {
+  margin-top: 8px;
+  display: flex;
+  justify-content: space-between;
+}
+
+.control-panel-basic-map .links a {
+  font-weight: bold;
+  color: #486865;
+  font-size: 11px;
+}

examples/basic-map/vite.config.js

@@ -1,17 +1,7 @@
-import {defineConfig, loadEnv} from 'vite';
-import {resolve} from 'node:path';
-
-export default defineConfig(({mode}) => {
-  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')
-      }
-    }
-  };
-});
+export default {
+  define: {
+    'process.env.GOOGLE_MAPS_API_KEY': JSON.stringify(
+      process.env.GOOGLE_MAPS_API_KEY
+    )
+  }
+};

examples/change-map-id/README.md

@@ -13,12 +13,14 @@ Go into the example-directory and run
 npm install
 ```
 
-Then start the example with
+To start the example with the local library run
 
 ```shell
-npm start
+npm run start-local
 ```
 
+The regular `npm start` task is only used for the standalone versions of the the example (CodeSandbox for example)
+
 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.
 

examples/change-map-id/index.html

@@ -21,7 +21,7 @@
   <body>
     <div id="app"></div>
     <script type="module">
-      import '../../website/src/styles.css';
+      import './src/styles.css';
       import {renderToDom} from './src/app';
 
       renderToDom(document.querySelector('#app'));

examples/change-map-id/package.json

@@ -7,6 +7,7 @@
   },
   "scripts": {
     "start": "vite",
+    "start-local": "vite --config ../vite.config.local.js",
     "build": "vite build"
   }
 }

examples/change-map-id/src/app.tsx

@@ -10,7 +10,7 @@ import {
 } from '@vis.gl/react-google-maps';
 import ControlPanel from './control-panel';
 
-const API_KEY = process.env.GOOGLE_MAPS_API_KEY as string;
+import {getApiKey} from './lib/get-api-key';
 
 const MapTypeId = {
   HYBRID: 'hybrid',
@@ -79,7 +79,7 @@ const App = () => {
   const [markerRef, marker] = useMarkerRef();
 
   return (
-    <APIProvider apiKey={API_KEY}>
+    <APIProvider apiKey={getApiKey()}>
       <Map
         mapId={mapConfig.mapId}
         mapTypeId={mapConfig.mapTypeId}

examples/change-map-id/src/control-panel.tsx

@@ -13,7 +13,7 @@ function ControlPanel({
   onMapConfigIdChange
 }: ControlPanelProps) {
   return (
-    <div className="control-panel">
+    <div className="control-panel-change-map-id">
       <h3>Change MapIds</h3>
       <p>
         The react-component can switch between multiple mapIds without having to
@@ -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">

examples/change-map-id/src/lib/get-api-key.ts

@@ -0,0 +1,20 @@
+export function getApiKey() {
+  const url = new URL(location.href);
+  const apiKey =
+    url.searchParams.get('apiKey') ||
+    (process.env.GOOGLE_MAPS_API_KEY as string);
+
+  if (!apiKey) {
+    const key = prompt(
+      'Please provide your Google Maps API key in the URL\n' +
+        '(using the parameter `?apiKey=YOUR_API_KEY_HERE`) or enter it here:'
+    );
+
+    if (key) {
+      url.searchParams.set('apiKey', key);
+      location.replace(url.toString());
+    }
+  }
+
+  return apiKey;
+}