Merge pull request #3 from stevent-team/feat/helpers

`createMeta` helper
stevent-team · May 17, 2022 · ed7b705 · ed7b705
2 parents 7529a70 + 79d5295
commit ed7b705
Show file tree

Hide file tree

Showing 19 changed files with 1,621 additions and 742 deletions.
diff --git a/.npmignore b/.npmignore
@@ -0,0 +1,4 @@
+.parcel-cache
+.DS_Store
+node_modules
+.vscode
diff --git a/.parcelrc b/.parcelrc
diff --git a/README.md b/README.md
@@ -1,49 +1,119 @@
 # 🪣 Epoxy
+
 Simple server-side per-route html injection
 
 ## Purpose
+
 Epoxy allows for running middleware on select HTTP routes that inject HTML into the served content.
-Simply point it at a static directory, define some routes in a script and you're off to the races :horse:!
+Simply point it at a static directory, define some routes in a script and you're off to the races! :horse:
 
 ## Usage
 
-Add as a dev dependency
+Add as a dependency
+
 ```bash
-yarn add --dev @stevent/epoxy
+yarn add @stevent/epoxy
+```
+
+### Options
+
+You can also run `npx epoxy --help` to see this information.
+
 ```
+epoxy <target> [routeFile] [options]
+
+target     Path to static directory
+routeFile  Path to router script
+
+Options:
+      --help     Show help                                                     [boolean]
+      --version  Show version number                                           [boolean]
+  -p, --port     port to use for http server                    [string] [default: 8080]
+  -h, --host     host to use for http server               [string] [default: "0.0.0.0"]
+  -i, --index    path to index html inside of target    [string] [default: "index.html"]
+```
+
+## Example
 
 Create a script to define your dynamic routes. *(requires .mjs extension)*
+
 ```js
 // Handlers are async functions returning HTML to be injected
 const routeHandler = async req => {
+  const { params } = req // Get route params from request
+
   return {
-    head: '<meta property="coolness" value="100">', // Injected into the end of the <head>
+    head: `<meta property="coolness" value="${params.coolness}">`, // Injected into the end of the <head>
     body: 'Howdy!' // Injected into the end of the <body>
   }
 }
 
-export default [
-  "/some/route/with/:param": routeHandler
-]
+export default {
+  '/some/route/with/:coolness': routeHandler
+}
 ```
 
+<details>
+  <summary>See an example using the `createMeta` helper</summary>
+
+  > ### `createMeta` Helper
+  >
+  > Epoxy comes with a helper that allows you to easily create meta tags from an object.
+  >
+  > ```js
+  > import { createMeta } from '@stevent/epoxy/helpers'
+  >
+  > const routeHandler = async ({ params }) => {
+  >   // Create a string of meta tags from the object passed in
+  >   const metaTags = createMeta({
+  >     coolness: params.coolness,
+  >     description: 'A pretty cool page',
+  >   })
+  >
+  >   return { head: metaTags }
+  > }
+  >
+  > export default {
+  >   '/route/:coolness': routeHandler
+  > }
+  > ```
+  >
+  > For more information about the helpers available in Epoxy, see the [readme](./helpers/README.md).
+</details>
+
 Then serve your static directory and dynamic routes!
+
 ```bash
 epoxy ./dist ./routes.mjs
 ```
 
 or setup an npm script
+
 ```js
 // package.json
 {
   "scripts": {
-    "serve": "epoxy ./dist ./epoxy-routes.mjs"
+    "serve": "epoxy ./dist ./routes.mjs"
   }
 }
 ```
 
-### Contributing
+## API
+
+Your route handler must be a javascript module (i.e. have the file extension `mjs`) so that it can be imported and used by Epoxy. It also has to export a default object with the structure:
+
+```js
+export default {
+  'express/js/route/:withParams': yourRouteHandlerFunction
+}
+```
+
+Each route must have a function to handle it, which will receive a `request` object from ExpressJS, from which you can learn about the request. See the express docs for the [request object](https://expressjs.com/en/api.html#req) for more information.
+
+## Contributing
+
 PRs and Issues are more than welcome :)
 
-### License
+## License
+
 Created by Stevent (2022) and licensed under MIT
diff --git a/helpers/README.md b/helpers/README.md
@@ -0,0 +1,26 @@
+# 🧼 Epoxy Helpers
+
+A collection of helpers to use with Epoxy
+
+## createMeta
+
+A function that will help create meta tags based on an object
+
+### Example
+
+```js
+import { createMeta } from '@stevent/epoxy/helpers'
+
+const meta = {
+  'og:title': 'My Page',
+  'og:description': 'Here lies my things',
+  'og:image': 'https://my.page/image.jpg',
+}
+
+console.log(createMeta(meta))
+/*
+  <meta property="og:title" value="My Page">
+  <meta property="og:description" value="Here lies my things">
+  <meta property="og:image" value="https://my.page/image.jpg">
+*/
+```
diff --git a/helpers/index.ts b/helpers/index.ts
@@ -0,0 +1 @@
+export { default as createMeta } from './src/createMeta'
diff --git a/helpers/package.json b/helpers/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "epoxy-helpers",
+  "version": "1.0.0",
+  "description": "Helpers for epoxy",
+  "main": "./dist/index.js",
+  "source": "./index.ts",
+  "types": "dist/types.d.ts",
+  "author": "Stevent",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stevent-team/epoxy.git",
+    "directory": "helpers"
+  },
+  "scripts": {
+    "build": "parcel build"
+  },
+  "devDependencies": {
+    "@parcel/packager-ts": "2.5.0",
+    "@parcel/transformer-typescript-types": "2.5.0",
+    "parcel": "^2.5.0",
+    "typescript": "^4.6.4"
+  }
+}
diff --git a/helpers/src/createMeta.ts b/helpers/src/createMeta.ts
@@ -0,0 +1,12 @@
+type MetaTags = {
+  [property: string]: string
+}
+
+const createMeta = (metaTags: MetaTags): string =>
+  Object.entries(metaTags)
+  .reduce((html, [property, content]) =>
+    `${html}<meta property="${property}" content="${content}">`,
+    ''
+  )
+
+export default createMeta
diff --git a/helpers/tsconfig.json b/helpers/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "sourceMap": true,
+    "outDir": "dist",
+    "strict": true,
+    "lib": ["esnext"],
+    "noImplicitAny": false
+  }
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		export { default as createMeta } from './src/createMeta'