feat: 🎸 v1 of @elderjs/plugin-random

packages/random/README.md

@@ -0,0 +1,41 @@
+# Elder.js Plugin: Random
+
+Easily preview a random page of a route by visiting a single url. This plugin should be used exclusively for development.
+
+## What This Plugin Does:
+
+When not running in `process.env.NODE_ENV === 'production'` this plugin does 2 things:
+
+1.  It creates a `/random/` route that lists each of your routes linking to `/random/routeName/`.
+2.  It intercepts requests to `/random/routeName/` and randomly serves a page for that route.
+
+## Benefits:
+
+Say that you have a route named `blog` that has 1000 entries. With this plugin you could visit `/random/blog/` and randomly design against any blog page instead of just one as most designers would do.
+
+This is a simplistic example, but when building major sites with 10,000s of pages you'll often encounter scenarios where pages of the same route differ dramatically based on business logic.
+
+By using this plugin, you can design and debug against random pages of a route without having to change the URL.
+
+At <a href="https://elderguide.com">ElderGuide.com</a> we've found this is especially useful when working on a unified design across a route that can vary dramatically.
+
+Having found this useful, it has now become a core part of our development process across all projects.
+
+## Install
+
+```bash
+npm install --save @elderjs/plugin-random
+```
+
+## Config
+
+```javascript
+plugins: {
+  '@elderjs/plugin-random': {},
+}
+```
+
+## Notes:
+
+- When using this plugin with the `@elderjs/plugin-browser-reload` remember that `/random/routeName/` will generate a new page each refresh. This can be annoying when working on CSS issues or thing that require stateful experiences on the front end.
+- If you are looking for the REAL url of a page look within `request.permalink` inside your `Layout.svelte` or `RouteName.svelte` files.

packages/random/Random.svelte

@@ -0,0 +1,19 @@
+<script>
+  export let settings, helpers;
+
+  const routes = Object.keys(helpers.permalinks).filter(
+    (a) => !(a.toLowerCase().includes('plugin') && a.toLowerCase().includes('random')),
+  );
+</script>
+
+<div class="container">
+  {#if routes.length > 0}
+    <ul>
+      {#each routes as route}
+        <li><a href="{settings.prefix}/random/{route}/">{route}</a></li>
+      {/each}
+    </ul>
+  {:else}
+    No routes registered to provide links to
+  {/if}
+</div>

packages/random/index.js

@@ -0,0 +1,78 @@
+const notProduction = process.env.NODE_ENV !== 'production';
+const plugin = {
+  name: '@elderjs/plugin-random',
+  description: 'Adds a /random/ page on previewer requests that displays all of the possible routes.',
+  init: (plugin) => {},
+  routes: {
+    pluginRandom: {
+      data: () => {},
+      template: 'Random.svelte',
+      permalink: ({ request, settings }) => {
+        if (request.slug && request.realRoute) return `/random/${request.realRoute}/`;
+        return `/random/`;
+      },
+      all: async () => [{ slug: '/random/' }],
+    },
+  },
+
+  hooks: [
+    {
+      hook: 'allRequests',
+      name: 'addRandomAndDebug',
+      description: 'Adds /random/route/ requests to allRequests. Also adds /debug/ to all requests.',
+      priority: 50, // default
+      run: async ({ helpers, data, settings, request, allRequests, routes, db }) => {
+        if (notProduction && settings.server) {
+          const randomRequests = Object.keys(routes).reduce(
+            (out, route) => [...out, { slug: 'random', realRoute: route, route: 'pluginRandom' }],
+            [],
+          );
+          return {
+            allRequests: [...allRequests, ...randomRequests],
+          };
+        }
+      },
+    },
+    {
+      hook: 'request',
+      name: 'updateRandomRequestWithRealRequest',
+      description: 'Adjusts random requests to go to a real page and route',
+      priority: 70, // Higher priority incase other plugins also need to be run on the same request.
+      run: ({ settings, request, allRequests, routes }) => {
+        if (notProduction && settings.server && request.slug === 'random' && request.route === 'pluginRandom') {
+          // filter requests
+          const routeRequests = allRequests.filter((r) => r.route === request.realRoute);
+
+          if (routeRequests && routeRequests.length > 0) {
+            // choose a random one
+            const randomRequest = Math.floor(Math.random() * (routeRequests.length - 1));
+            // update the request
+            const request = routeRequests.slice(randomRequest, randomRequest + 1)[0];
+
+            const route = routes[request.route];
+            return {
+              request,
+              route,
+            };
+          }
+        }
+      },
+    },
+    {
+      hook: 'request',
+      name: 'addAllRequestsToDebugDataObject',
+      description: 'Adds the allRequests array to the data object for /debug/',
+      run: ({ helpers, data, settings, request, allRequests }) => {
+        if (notProduction && settings.server && request.slug === 'debug' && request.route === 'debug') {
+          return {
+            data: Object.assign({}, data, {
+              allRequests: [...allRequests],
+            }),
+          };
+        }
+      },
+    },
+  ],
+};
+
+module.exports = plugin;

packages/random/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@elderjs/plugin-random",
+  "version": "0.1.38",
+  "description": "Easily preview a random page of a route by visiting a single url. This plugin should be used exclusively for development.",
+  "keywords": [
+    "elderjs",
+    "svelte",
+    "elder",
+    "random",
+    "debug"
+  ],
+  "author": "Nick Reese <nick@mbp.com>",
+  "homepage": "https://github.com/Elderjs/plugins#readme",
+  "license": "MIT",
+  "main": "index.js",
+  "directories": {},
+  "files": [
+    "index.js",
+    "Random.svelte"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Elderjs/plugins.git"
+  },
+  "scripts": {
+    "test": "echo \"Error: run tests from root\" && exit 1"
+  },
+  "bugs": {
+    "url": "https://github.com/Elderjs/plugins/issues"
+  }
+}