DEV Community: Ramsay

Build a Redux-like Global Store Using React Hooks

Ramsay — Thu, 17 Jan 2019 16:57:01 +0000

We'll pretend like I wrote an interesting preface to this article so we can skip to the good stuff. In short, we'll use useReducer and useContext to create a custom React hook that provides access to a global store, similar to redux.

I'm in no way suggesting this solution has feature-parity with redux, because I'm sure it doesn't. By "redux-like", I mean that you'll be updating the store by dispatching actions, which resolve to mutate and return a fresh copy of the mutated state. If you've never used redux, pretend like you didn't read this.

Before we start, I created a Code Sandbox with the full implementation, if you'd rather just play around with the code.

The Hook

Let's start by creating the Context that will contain our state object and dispatch function. We'll also the useStore function that will act as our hook.

// store/useStore.js

import React, { createContext, useReducer, useContext } from "react";

// we'll leave this empty for now
const initialState = {}

const StoreContext = createContext(initialState);

// useStore will be used in React components to fetch and mutate state
export const useStore = store => {
  const { state, dispatch } = useContext(StoreContext);
  return { state, dispatch };
};

Since everything is stored in React Context, we'll need to create a Provider that gives us the state object and the dispatch function. The Provider is where we'll use useReducer.

// store/useStore.js

...
const StoreContext = createContext(initialState);

export const StoreProvider = ({ children }) => {
  const [state, dispatch] = useReducer(reducer, initialState);
  return (
    <StoreContext.Provider value={{ state, dispatch }}>
      {children}
    </StoreContext.Provider>
  );
};
...

We use useReducer to get state, and dispatch, because that's what useReducer does. We pass state and dispatch to the provider. We can wrap any React component we want with <Provider/>, and that component can then use useStore to interact with the state.

We haven't created the reducer yet, that's the next step.

// store/useStore.js
...
const StoreContext = createContext(initialState);

// this will act as a map of actions that will trigger state mutations 
const Actions = {};

// the reducer is called whenever a dispatch action is made.
// the action.type is a string which maps to a function in Actions.
// We apply the update to existing state, and return a new copy of state.
const reducer = (state, action) => {
  const act = Actions[action.type];
  const update = act(state);
  return { ...state, ...update };
};
...

I'm a big fan of separating actions/state into logical groups. For example, you might want to keep track of your counter's state (this is the classic Counter example). At the same time, you might also want to keep track of current User state, like if a user is logged in, and what their preferences are. In some component, you might need access to both of these different "states", so keeping them in one global store makes sense. But we can separate out the actions into logical groups, like a userActions and a countActions, which will make managing them much easier.

Lets create a countActions.js and userActions.js file in the store directory.

// store/countActions.js

export const countInitialState = {
  count: 0
};

export const countActions = {
  increment: state => ({ count: state.count + 1 }),
  decrement: state => ({ count: state.count - 1 })
};

// store/userActions.js

export const userInitialState = {
  user: {
    loggedIn: false
  }
};

export const userActions = {
  login: state => {
    return { user: { loggedIn: true } };
  },
  logout: state => {
    return { user: { loggedIn: false } };
  }
};

In both of these files, we export initialState because we want to combine these in useStore.js into one initialState object.

We also export an Actions object that provides functions for mutating state. Notice that we don't return a new copy of state, because we do that in the actual reducer, in useStore.js.

Lets import these into useStore.js to get the complete picture.

// store/useStore.js

import React, { createContext, useReducer, useContext } from "react";

import { countInitialState, countActions } from "./countActions";
import { userInitialState, userActions } from "./userActions";

// combine initial states
const initialState = {
  ...countInitialState,
  ...userInitialState
};

const StoreContext = createContext(initialState);

// combine actions
const Actions = {
  ...userActions,
  ...countActions
};

const reducer = (state, action) => {
  const act = Actions[action.type];
  const update = act(state);
  return { ...state, ...update };
};

export const StoreProvider = ({ children }) => {
  const [state, dispatch] = useReducer(reducer, initialState);
  return (
    <StoreContext.Provider value={{ state, dispatch }}>
      {children}
    </StoreContext.Provider>
  );
};

export const useStore = store => {
  const { state, dispatch } = useContext(StoreContext);
  return { state, dispatch };
};

We did it! Take a victory lap, then come back and we'll take a look at how to use this in a component.

Welcome back. I hope your lap was victorious. Let's see useStore in action.

First, we can wrap our initial App component in the <StoreProvider/>.

// App.js

import React from "react";
import ReactDOM from "react-dom";
import { StoreProvider } from "./store/useStore";
import App from "./App";

function Main() {
  return (
    <StoreProvider>
      <App />
    </StoreProvider>
  );
}

const rootElement = document.getElementById("root");
ReactDOM.render(<Main />, rootElement);

We're wrapping App in StoreProvider so an child component will have access to the value in the provider, which is both state and dispatch.

Now, lets say we had an AppHeader component that has a login/logout button.

// AppHeader.jsx

import React, {useCallback} from "react";
import { useStore } from "./store/useStore";

const AppHeader = props => {
  const { state, dispatch } = useStore();
  const login = useCallback(() => dispatch({ type: "login" }), [dispatch]);
  const logout = useCallback(() => dispatch({ type: "logout" }), [dispatch]);

  const handleClick = () => {
    loggedIn ? logout() : login();
  }

  return (
    <div>
      <button onClick={handleClick}> {loggedIn ? "Logout" : "Login"}</button>
      <span>{state.user.loggedIn ? "logged in" : "logged out"}</span>
      <span>Counter: {state.count}</span>
    </div>
  );
};

export default AppHeader;

Here's a Code Sandbox will the full implementation!

Leveraging Node Modules to Provide Offline Documentation

Ramsay — Mon, 14 Jan 2019 22:09:12 +0000

Are you a young, hip, developer-on-the-go? Neither am I, but I do tend to do some application development in situations where I don’t have access to the internet. Also I’m not hip. And youth is fleeting.

Anyway.

There are very good solutions for obtaining offline-documentation. DevDocs comes to mind, because it offers great offline documentation storage for lots of well-used software, and it has tons of features. In fact, you should probably just use that. However, you can’t just add offline documentation for any package you want. There is some gatekeeping that occurs.

If an existing solution like DevDocs doesn’t suit your needs, you can leverage the documentation that ships with the packages you’ve installed in your application. That’s right, I’m talking about README.md files.

Over the weekend ™️, I had the idea of building a little CLI tool that could create an express server that would look for the node_modules directory and serve up the contents of each packages’ README.md file. The tool would also provide a web interface for you to search node_modules for packages. It could also uses IndexedDB to store favorites offline.

So I did it. The result is Module Docs and you can install it as a Node package.

You can install it globally, or per project. After installing, start the cli by running:

$ module-docs start

You can create an npm script that will automatically start module-docs as part of the dev process. Here’s how I use it:

{
  "scripts:" {
    "start": "npm run start:docs && webpack-dev-server",
    "start:docs": "module-docs start"
  }
}

You can configure module-docs for each project you want to use it on by creating a module-docs.config.js file in the root of that projects’ directory. Currently, you can provide an array of package names to include as favorites, like so:

// module-docs.config.js
module.exports = {
   favorites: ["react", "react-apollo", "react-apollo-hooks"]
}

If you just want to use it, you can stop reading here and go live your best life. If you want to read on about how it was built, bless up and keep reading.

Creating the CLI

In order to create the cli, I’ll use commander.js, which is a very popular CLI building tool.

const program = require("commander")
const makeServer = require("./server/serve")
const path = require("path")

// gets the config file from the working directory of the application 
const getConfig = () => {
  const configPath = path.join(process.cwd(), "./module-docs.config.js")
  const config = require(configPath)
  return config ? config || null
}

// using commander, execute the start command which spins up the express server
program.command("start").action(() => {
  const modulePath = path.join(process.cwd(), "./node_modules")
  const config = getConfig()
  makeServer(modulePath, config)
})

program.parse(process.argv)

This is the jumping off point for the entire module_docs package. Its what allows you to run module-docs start to start up the express server. Let’s take a look at the server.

Building The Server

The server is a pretty basic Node server build using Express. It uses webpack-dev-middleware to create a dev server that will serve up a React application for the web UI.

const express = require("express")
const webpack = require("webpack")
const config = require("../webpack.config")
const devMiddleware = require("webpack-dev-middleware")
const compiler = webpack(config)
const bodyParser = require("body-parser")

// controller to handle API requests
const FileController = require("./controllers")

// Probably should make this configurable 
const PORT = 4444


module.exports = (modulePath, config) => {
  const app = express()

  app.use(bodyParser.json())

  // start webpack dev server
  app.use(
    devMiddleware(compiler, {
      open: true,
      stats: "errors-only"
    })
  )

  // handles getting package names from node_modules
  app.post("/modules", FileController.getFiles(modulePath, config))

  // handles getting the package info and README from a package
  app.post("/module/:name", FileController.getPackage(modulePath))

  app.get("*", function response(req, res) {
    res.sendFile("./client/template.html", { root: __dirname })
  })

  app.listen(PORT, () => {
    console.log(`Module Docs is running at http://localhost:${PORT}`)
  })
}

As you can see, there are two API endpoints. The first endpoint handles getting the directory names from node_modules. The second endpoint gets the README contents and parses package.json for information about the package. Currently, the UI just displays the package version and a link to the package’s homepage, if there is one.

To handle the POST request, I’ve created a FileController. This is where all the heavy lifting is.

The FileController

This file could definitely use some refactoring. That being said, I’ll break this file down into chunks. First, the utility functions and imports:

const fs = require("fs")
const pipe = require("lodash/fp/pipe")
const some = require("lodash/some")
const promisify = require("util").promisify
const readdir = promisify(fs.readdir)
const readFile = promisify(fs.readFile)

// directories to exclude from the search
const blacklist = [".bin", ".cache", ".yarn-integrity"]

const filterThroughBlacklist = files =>
  files.filter(f => !blacklist.includes(f))

// check to see if the list of files includes the filename
const checkFilesForFile = files => fileName =>
  some(files, f => f.name === fileName)

// Get all the files in the package that are directories. This is used
// for mono-repos are scoped packages that don't contain README files directly. 
// I could probably refactor this and the blackListFilter into one util function
const getDirectories = files =>
  files.filter(f => f.isDirectory() && f.name !== "node_modules")

// checks a package directory to see if it contains a README or a package.json file
const checkPackage = files => {
  const checkFilesFor = checkFilesForFile(files)
  return {
    hasReadme: checkFilesFor("README.md"),
    hasPackageInfo: checkFilesFor("package.json")
  }
}

// gets the content of the README and the package.json file, if they exist
const getDirectoryContent = async directory => {
  const files = await readdir(directory, { withFileTypes: true })
  const { hasReadme, hasPackageInfo } = checkPackage(files)
  const readmeContent =
    hasReadme && (await readFile(`${directory}/README.md`, "utf8"))

  const packageInfo =
    hasPackageInfo && (await readFile(`${directory}/package.json`, "utf8"))

  return {
    files,
    readmeContent,
    packageInfo
  }
}

// If a package has sub-directories, check each directory for a README and package.json
// If they exists, get contents of each and return
const getPackagesFromChildren = parentDir => children => {
  const readmes = children.map(async child => {
    const childDir = `${parentDir}/${child.name}`
    const { readmeContent, packageInfo } = await getDirectoryContent(childDir)
    return readmeContent || packageInfo
      ? {
          name: child.name,
          path: `${childDir}/README.md`,
          content: readmeContent,
          info: packageInfo
        }
      : {}
  })

  return Promise.all(readmes)
}

It’s important to note that I’ve created a blacklist of files to exclude from searching, because they are in node_modules but aren’t useful for our purposes. I’m sure this list is not all encompassing.

Also, we should provide a list of sub-directories (children) that contain README and package.json files, in case the package in question is a mono-repo, or a scoped package, like babel. This is what getPackagesFromChildren does.

The above util functions will be used in the FileController handlers. Let's take a look at them.

// gets directory names from a path, excluding blacklisted names. Returns an array of strings.
exports.getFiles = (path, config) => async (req, res) => {
  const files = await readdir(path)
  const filteredFiles = filterThroughBlacklist(files)
  res.send({ files: filteredFiles, config })
}

// Gets README content for package and all first-level children.
exports.getPackage = path => async (req, res) => {
  const name = req.params.name
  const dir = `${path}/${name}`

  try {
    const { files, readmeContent, packageInfo } = await getDirectoryContent(dir)
    const children = await pipe(
      getDirectories,
      getPackagesFromChildren(dir)
    )(files)

    const pkg = {
      path: dir,
      content: readmeContent,
      info: packageInfo,
      children: children
    }

    res.send({ pkg })
  } catch (err) {
    console.log("Unable to scan directory: " + err)
    res.send({ pkg: "No Readme Found" })
  }
}

That’s pretty much it for the server-side of things.

As for the front-end, its built using React (as of writing 16.8-alpha, so I can use those sweet sweet hooks). You're best bet is to play around with the CodeSandbox below.

Wrap Up

Not bad for a weekend. I’m going to keep working on some other features that I’d personally like to use, like being able to add custom notes to each package, and being able to link and fetch documentation and saving that offline as well. Let me know what you think!

Creating and Animating a Modal Component as a Child Route Using Vue

Ramsay — Thu, 08 Feb 2018 16:04:46 +0000

Here’s a link to the repo.
Here’s a live demo.

As I work on side projects, I sometimes stumble upon a pattern that I really
like. This is one of those times. Today, I’ll show you how to implement a detailed view of a list item as a modal using a child route.

If you play around with the live demo you'll notice that the URL updates when a rule is clicked on and a modal renders. This means that we can refresh the page and the modal will render with the list of rules in the background. It’s a nice touch because we’ll always be able to see the rule in the context of the game.

The Router

We have a parent route called Game that has two child routes — Game Rules and Game Rule. I’m using a separate route for rules, because eventually I’m going to let user’s create groups of rules called rulesets, and I would like to be able to separate that out as another route, eventually.

Of note, the Game Rules route renders only one component for the page view (lines 24–26) while the Game Rule route also renders the RuleSingle component for the rule view (line 36). This will make sense once you see the GameSingle component.

Also of note, we’re leveraging router meta which will be used in the GameSingle component to determine if the modal should be shown. We want it to show for Game Rule but not for Game Rules.

The GameSingle Component

I’m excluding all the styling from the following components for brevity’s sake.

This component has two <router-view> tags, one for the page (line 10), and one for the rule (line 15). Note that the <modal> component (shown below) will only be shown if showModal is true. We determine if showModal is true based on the route meta (line 31). Lastly, we’re going to want to watch the route meta value and update showModal accordingly (lines 35–39). When a user clicks on a rule, the route changes causing the showModal value to be true, which in turn renders <modal> and its children.

The Modal Component

We wrap the entire component in a <transition> and use custom functions to handle the enter and leave animation. When the modal is rendered it fades in, and when a user clicks the close button, the router goes backwards in history a step causing the modal to fade out.

Conclusion

There are many ways to implement modals. One way I’ve done this in the past is by creating a modal component in the root App component and use Vuex actions to show it and tell it what content to use. It’s always felt a bit cumbersome to me, but its definitely a viable solution. I like this solution because it doesn’t clutter up Vuex state (which seems unnecessary for this type of interaction) and still allows the modal component to be re-usable.

Introducing VuePress: WordPress development with Vue and GraphQL.

Ramsay — Tue, 02 Jan 2018 22:31:54 +0000

Preface:

About two years ago I created WordExpress, which was my first attempt at developing WordPress sites using only JavaScript. It got a decent amount of buzz and currently has around over 1400 stars on GitHub. The number of stars isn’t at all important, but it does highlight one thing: developers want to develop WordPress using JavaScript on the front-end.

One of the most difficult things to overcome at the time was server-side rendering with GraphQL. WordPress sites require search engine optimization, and you can’t begin to do SEO without server-side rendering. A lot has changed in two years, and server-side-rendering with GraphQL is now much easier thanks to Apollo.

In the past month, I’ve revisited WordExpress and I’ve come up with a solution using Vue instead of React. This is totally doable using React (in fact a big piece of the puzzle is the WordExpressSchema which is front-end agnostic) but I’ve been using Vue a lot and they have great documentation on server-side rendering, so I decided to give it a go.

I’ve called this new solution VuePress because I’m very clever with words.

The VuePress Architecture

On the back-end, VuePress consists of a node server (using express) that has a GraphQL endpoint. The GraphQL endpoint uses GraphQLExpress from Apollo, which accepts a schema. This is where WordExpressSchema comes in. You can (and should!) read the documentation on the schema. In short, the schema has queries which are resolved by connecting to a WordPress database and getting data directly from it.

On the front-end, VuePress consists of Vue components. Some of these components contain GraphQL queries. When the server gets a request, it determines which components to render, prefetches the required data from GraphQL, pipes that data through a template, and finally renders the HTML.

Making A Blog

Getting Started

The code in the VuePress repo contains pretty much every thing you need to get started. First, clone the repo and follow the instructions in the readme to get started.

$ git clone https://github.com/ramsaylanier/VuePress.git

A note about custom fields: I personally use the advanced-custom-fields plugin for WordPress, and I use the pro version. You absolutely don’t need to use this plugin, but it makes life much easier, and all the VuePress documentation assumes you are using it.

After following the directions, you can start the development server.

$ npm run dev

You should get something like this:

Lets change the layout of the homepage to include a page header.

Now it should look a little nicer:

Creating A Post List

First, lets create a page that will show all of our posts.

Notice the value for the Layout Component is PostList, which generates some extra custom fields (this is why ACF is nice!). The PostType drop down will tell the PostList component which post type in WordPress to render. Right now, we only have posts which is the default. VuePress also allows you to render different Post Item Components for each post list. Imagine you had two pages — a list of Articles and a list of Photographs. The list items in each page would probably be designed differently (articles would have text, photographs would have images), so you’d probably want to use a different component to render that item. You could create a whole new Layout Component with a different list, but that is more work.

Now, lets add the new Posts page to our primary-navigation menu.

Save the menu and refresh your application browser. You should see that the posts page is now in the header menu. That page looks like this:

Voila, we have a very simple blog in just a few steps.

Creating a Custom Layout Component

Lets say we want to create a page that has a sidebar that has its own menu of external links. So far, we haven’t had to touch any application code, but that’s about to change. First, we need to make some updates to our custom fields.

In the WordPress back-end, go to Custom Fields -> FieldGroups -> PageFields. Select page fields and add a new value to the LayoutComponent field.

Save the changes by clicking the Update button on that far right. Now, lets create a new page field called SidebarMenu that will let use render a custom menu by name. We only want this field to show up on pages that have the PageWithSidebar layout. Click the AddField button.

And further below, we want to add some conditional logic on when to display this field.

Save the changes.

Now, lets create a new menu for the sidebar. My menu will be a collection of links to Vue resources that I like. Yours can be whatever! Here’s what my menu looks like:

Now lets create a new page that will use the sidebar and the custom menu. You can name the page whatever you want — I’ve named it Resources.

Lastly, you’ll need to remember to add the new page to your primary-navigation menu.

Great! That’s all we need to do in the WordPress back-end. Now, we’ll need to create the custom layout file.

The layout components are located in /src/components/page/layouts. In that directory, you’ll see the existing layout components. Create a new file called PageWithSidebar.vue. Its going to look like this:

<template>
  <div class="wrapper">
    <menu-container class="sidebar" :menuName="getSidebarMenuName()">
      <ul class="menu" slot-scope="menu">
        <li class="item" v-for="item in menu.items" :key="item.id">
          <menu-link :link="item.navitem"/>
        </li>
      </ul>
    </menu-container>
    <div class="body">
      <post-content :content="page.post_content"/> 
    </div>
  </div>
</template>

<script>
import MenuContainer from '@/components/menu/menuContainer'
import MenuLink from '@/components/menu/menuLink'
import PostContent from '@/components/post/PostContent'
export default {
  name: 'page-with-sidebar',
  props: ['page'],
  components: {
    MenuContainer, MenuLink, PostContent
  },
  methods: {
    getSidebarMenuName () {
      return this.page.post_meta.filter(item => {
        return item.meta_key === 'sidebarmenu'
      })[0].meta_value
    }
  }
}
</script>

There are several things to note. First, notice the custom menu-container component. This component contains a GraphQL query. It accepts a prop called menuName and uses that to query GraphQL and get the items in the menu. But first, we have to get the name of the menu from the custom field of the page we are currently on. For that, we have to do some filtering of the page’s post meta.

This is a good time to mention that VuePress comes equipped with GraphiQL — an in-browser IDE for exploring GraphQL. You can go to localhost:3000/graphiql and see it. Click here and it will open up GraphiQL with the page query for a page with a name “resources”, which looks like this.

Notice the meta_key for sidebarmenu and the meta_value is resources-menu. Going back to the PageWithSidebar component, you can see that the getSidebarMenuName is simply filtering the post meta for the sidebarmenu key and getting its meta_value.

Now, lets look at what a menu query looks like. Click here for that link.

Now, menus are arguably one of the craziest things in WordPress because of how they are saved in the database. Each menu item has a navitem that is either a link to another post, or a custom link with its own post meta. In the case of this sidebar menu, all the links are custom. Luckily for you, though, I’ve created a MenuLink component that will determine if the link is internal or external, so you just need to pass the navitem to it.

Here’s the final result of the PageWithSidebar component.

Wrapping Up

While VuePress is still in heavy development (I haven’t even written any tests for it which makes me a bad person), I think its a step in the right direction. It feels good to be able to write Vue components instead of using PHP templates. Its nice to have scoped CSS or CSS modules built in. Its nice to finally have server-side rendering.

Over the course of the next couple of weeks I plan on really tightening up some documentation as well as developing a comprehensive testing suite. If you’d like to contribute, please hit me up on twitter. Happy developing!