Fresh Starts

Recently at work, I started a new application from scratch. If you’ve had this honor, then you know how energizing it can be while everything is clean and working just the way you planned; naming conventions are in place, file and directory structures are intuitive, unit tests are plentiful. It’s easy to be consistent when it’s just you.

If you’ve ever jumped into working on a “legacy” codebase, then you know what it’s like after a couple years and X number of engineers have come and gone, leaving their own unique footprints. When someone isn’t enforcing conventions, things can get pretty wild west in a short period of time.

With Great Power Comes Great Responsibility

While developing a new codebase is a powerful feeling, my ego was tampered with the duty to protect future developers. Let’s face it, JavaScript applications these days can be a little daunting. A typical Redux app potentially has a LOT of files:

  • Containers
  • Components
  • Reducer
  • Actions
  • Constants
  • Not to mention Unit Tests, build files, config, utils, pages/routes

So, how can we follow conventions to a T, but also not get in the way of quickly adding features?

Plop (It’s not just fun to say!)

Plop is “a micro-generator framework that makes it easy for an entire team to create files with a level of uniformity” (according to their docs). So what does that mean? It’s a combination of Handlebars Templating and configured CLI prompts to update existing files, or generate new files. You can read their docs for an explanation of how it works, but here are some examples of why it worked for me:

  • Boost efficiency by eliminating leg work
  • Enforce conventions by creating files and naming things from a template
  • Promote unit testing by providing boilerplate tests
  • Promote documentation of new files by generating a README.md

For example: An engineer needs a container component for a new feature:

She runs:

npm run g:container

…and answers a couple CLI prompts to name things. Immediately after that, she has a directory scaffolded out with:

  • A new connected component (Container)
  • A new .scss file added and imported with classNames in place on the JSX
  • A new reducer
  • A new actions file
  • A new constants file
  • A Unit Tests file with working tests scaffolded out
  • A README file for that component with a good start in place
  • Updated main docs file to link to that README
  • Update store to know about that new reducer

Plop basically does all the administrative labor of adding a new feature to an app, allowing you to move forward with the creation of the feature itself. And the best part is that everything is named according to convention!

The Caveats

Effort: I’ll be honest, I borrowed a lot of ideas from other open source projects using plops. The example above would have been quite tedious if I were not standing on the shoulders of giants. Getting things right for my needs takes a fair amount of logic and configuration. I’d suggest starting small: Don’t try to account for every little thing, and be sure to look at examples of others’ configurations for ideas.

One plop doesn’t fit all: You can’t account for all situations in plops; some things are just one-offs. As I mentioned, they take time to get right, and you’d only want to create generators for things that you’d be doing regularly or that you’d expect someone else to have to do again.

Conclusion

Consistency is something that makes a project feel more sane, and it contributes to a better developer experience. Using a micro-generator has definitely helped me in that sense. There are other generators out there (Yeoman for one), but the simplicity and portability of Plop is what made it really effective for my team. It’s also fun to say, especially out of context.

Plop.

Some examples for reference:

https://github.com/react-boilerplate/react-boilerplate
https://github.com/scalable-react/scalable-react-boilerplate




Tagged with: