Node Style Guide

Node Style Guide

Talk from Front Porch 2015, on using Node and React to make an interactive style guide.

A video of our talk is available here…

https://youtu.be/SoEPoww5BdA

3e101126b514c65ee531e47bd6281ba3?s=128

Nathan Smith

October 20, 2015
Tweet

Transcript

  1. ‹#› © 2015 T7 July 24, 2015 October 20, 2015

    Node.js and Style Guides
  2. Nathan Smith! Principal Front-End Architect Mundi Morgado! Director of Front-End

    Architecture Introductions
  3. ! Github Repo:! http://github.com/t7/style-guide-example! ! Slides:! http://j.mp/node-style-guide! ! Mundi Morgado!

    @mundizzle! ! Nathan Smith! @nathansmith
  4. ! TandemSeven! Developers :) !

  5. We Begin with a Simple Assumption…! ! People are not

    mind readers. We are visual in nature. We tend not to follow instructions well.
  6. We do not like being told what to do, but

    we do like knowing how things fit together.! ! (Even if we end up taking them apart and making them our own.)
  7. We Enjoy Knowing the "Why" of Design

  8. Overview • What is a style guide?! • Examples of

    style guides! • Rolling your own framework! • Using NPM and Webpack! • Using ES6 and React! • Using PhantomJS! • DEMO! :)
  9. What Is a! Style Guide?

  10. What a Style Guide May Contain! ! It is about

    design governance and code standards.! ! What we mean by that is:! ! • No more rogue agents, shooting from the hip with unique snowflake designs, or developers building one-off widgets in code.
 • Everything in a project should exist for a reason, and its purpose should be documented accordingly.
 • This allows for easier and quicker onboarding, where someone can refer back to established patterns and code conventions.
 • It gives you a defensive point reference, in case implementation goes awry. It's a "last known good" state of UI development.! ! (Design coworker Brandy Taylor coined the term "Design Governance.")
  11. No More One Offs

  12. Managing Expectations! ! ! “The movie opens with a gentleman

    in a jacket, sporting a mustache…”
  13. Managing Expectations: Perception

  14. Managing Expectations: Perception vs. Reality

  15. In Addition to Design, We Also Document! ! • Accessibility

    expectations, with a tie-in to SEO to "sell" it.! ! • AJAX does not mean "Accessibility Just Ain't eXciting."! ! • Browser requirements (January 12, 2016 = R.I.P. IE8).! ! • Best practices:
 • Responsive design, explanation and breakpoints.
 • What we will or will not attempt to achieve outside of CSS.
 • Border-radius, box-shadow, gradients, opacity, etc.
 • Non-native form controls. Styling is okay, but recreating something the browser gives you "for free" is not.
  16. None
  17. None
  18. Really, your style guide can contain anything! :) http://thosewhowanderblog.com/2013/01/15/bus2alps-loves-chuck-norris/

  19. Examples of! Style Guides

  20. None
  21. None
  22. In Summary Just use Bootstrap.! Thanks for coming! :)

  23. None
  24. Clarification! ! There is nothing inherently wrong with using a

    third party
 library or framework (that is half our job), assuming that…
 ! • The library or framework that you are using
 solves a problem you actually have.
 • You are not "solutioneering," attempting to use a
 tool designed to solve other people's problems.! ! • You are using it as a "tool," not a "crutch."! ! ! The more invested you are in a "kitchen sink" framework,
 especially if it lacks extensibility, the harder it is to adapt
 to change over the lifetime of a given app or product.
  25. http://legoquestkids.blogspot.com/2011/02/30-pieces-quest-34.html One Size Does Not Fit All. Never Use Absolutes.

  26. None
  27. None
  28. None
  29. None
  30. None
  31. None
  32. None
  33. Or, You Could Always Just

  34. Rolling Your! Own Framework

  35. How We Made Our Style Guide Framework http://nodejs.org

  36. How We Made Our Style Guide Framework http://npmjs.org

  37. How We Made Our Style Guide Framework https://en.wikipedia.org/wiki/Blood,_Sweat_%26_Tears

  38. Note: We Do Not Recommend Rewriting Your Framework Three Weeks

    Before a Presentation! ! September 25th, 2015! ! Nathan: "When you get back from Burning Man, let's start working on our Front Porch slides."! ! Mundi: "Actually, why don't we go ahead and rewrite it using React on the client and server."! ! Nathan: O_o
  39. (Nathan handled this idea gracefully, of course.)

  40. October 1st, 2015! ! We officially started cranking on the

    new style guide. (╯°□°)╯︵ ┻━┻
  41. Our Requirements for ISG v2! ! • Statically generated.! •

    Portable.! • Server agnostic.! • Zip-able (can be sent as flat-file).! ! • Stays fresh.! • Can be built from the live app's codebase.! • App should not "know" about the style guide.
  42. Our Requirements for ISG v2! ! • Contains brand standards.!

    • Has room to grow.! • Can have non-dev contributors.! ! • Automated listing of unique patterns.! • Live working UI.! • Code examples: JavaScript and HTML.! ! • Houses screenshots and technical specs.
  43. Used in Both v1 and v2 • Lodash.js: data manipulation.!

    • Glob: file/directory globbing.! • FS-Extra: file system utilities.! • PhantomJS: for screenshots.
  44. What Changed from v1 to v2 • Handlebars: JS templating.!

    • JSHint: JS validation.! • Sass or flat-file CSS.! • Highlight.js: syntax coloring.! • YAML: for metadata.! ———! • Express: dev server.! • Socket.io: live reloading.! • Chokidar: file watching.! • Async: task automation. • React: JS templating.! • Standard: JS validation.! • Sass/CSS and PostCSS.! • Prism.js: syntax coloring.! • JS/JSON: for metadata.! ———! • Webpack: dev server.! • ES6 to ES5 conversion.! • JS module loading.! • NPM: task automation.
  45. Using NPM! and Webpack

  46. None
  47. Example NPM package.json ! { "scripts": { "test": "standard", "prestart":

    "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }
  48. Example NPM package.json ! { "scripts": { "test": "standard", "prestart":

    "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }
  49. Example NPM package.json ! { "scripts": { "test": "standard", "prestart":

    "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }
  50. Example NPM package.json ! { "scripts": { "test": "standard", "prestart":

    "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }
  51. Example NPM package.json ! { "scripts": { "test": "standard", "prestart":

    "npm install", "start": "webpack-dev-server --hot", "prebuild": "npm test && rm -r ./build", "build": "webpack", }, "devDependencies": { "standard": "^5.3.1", "webpack": "^1.10.1", "webpack-dev-server": "^1.9.0" } }
  52. Gotchas with NPM! ! • We love that using NPM

    for task automation removes the need to use a task runner like Grunt or Gulp.! ! • However, chaining together commands with NPM scripts can get hairy. There are tradeoffs either way.! ! • Closer to the metal, but more manual curation.
  53. Gotchas with NPM! ! Cross platform portability…! ! For example,

    {"clean": "rm -r ./build"} will not work on Windows.! ! Instead, use something like Trash-CLI.! ! It abstracts this functionality across platforms.! ! https://github.com/sindresorhus/trash-cli
  54. Example of Trash-CLI ! // Before. {"clean": "rm -r ./build"}

    ! ! // After. {"clean": "trash ./build"}
  55. Things to Consider! ! • If it suits your project's

    needs, using Grunt or Gulp can help ease the burden of automation.! ! • Ultimately, both Gulp and Grunt use Node under the hood anyway.! ! • Using NPM scripts is like an "API" to your build automation. Even if you are using Grunt or Gulp, you can map tasks to package.json too.
  56. Using ES6! and React

  57. None
  58. I Will Admit… React is awesome. I was basically super

    wrong.! ! Over the years, I have only found a short list
 of concepts to be exciting in web development.! ! • CMS powered sites.! • jQuery.! • Sass.! • React.
  59. ECMAScript 6 is Weird (in a Familiar Way) The way

    we are using React is…! ! • ES6 classes, transpiled to ES5 (via Babel).! • JSX ("HTML" in JS), which Nathan thought he would dislike.! • "Standard" for our JS linter.! • ASI: Automatic Semicolon Insertion – Don't kill us!! • Otherwise, it has generally agreeable conventions.! ! Note: ES6 and JSX feel different enough that going ASI (too) was not actually that big of a stretch. MAKE NEW ALL THE THINGS.
  60. None
  61. None
  62. None
  63. Using React on the Server – aka "isomorphic"! – aka

    "universal" – aka "cool kids" • Create JSX "layout" components.
 • Then, using Node…
 • Use webpackRequire() to load the template and
 resolve dependencies: CSS, Markdown, images, etc.
 • Use ReactDOMServer.renderToStaticMarkup()
 to process the template and return HTML.
 • Save the rendered HTML output to disk.
  64. None
  65. Using PhantomJS to! Create Screenshots

  66. None
  67. Our Approach to Creating Screenshots! ! • We create a

    PhantomJS script to iterate through a list of paths, taking a screenshot of each at mobile, tablet, and desktop widths.! ! • We generate a list of full-page screenshots that are linked to each actual "application" screen.
  68. PhantomJS Gotchas! ! • A server must be running for

    phantom to be able to access the pages you want to screenshot. Keep your server on!! ! • We wanted to use the awesome PageRes library. However, it ships with PhantomJS 1.x which uses an old version of WebKit. This has poor support for CSS3, making our screenshots look less than ideal.
 
 https://github.com/sindresorhus/pageres
  69. PhantomJS Gotchas! ! • PhantomJS 2.x is not easily installed

    via NPM (in our experience).! ! • You have to manually download and install PhantomJS yourself, which makes automation difficult. It is not as easy as:
 "npm install ..."! ! • Activity on the project seems to have slowed.! ! • In the future, we may look at using SlimerJS (based on Firefox).
  70. PhantomJS Pro Tip™! ! We are adding <html data-mode="phantom"> to

    the document, so that approaches like having a "sticky footer" don’t jack with the page's natural height. Basically, forcing something other than the <html> tag to scroll will confuse Phantom.! ! You can manually add this to the HTML tag (or via console) as you build pages, to check what PhantomJS will "see" when it goes to screenshot each page. This approach allows you to (de-)target Phantom via CSS.
  71. None
  72. None
  73. Okay, Let's Dig! Into This Demo

  74. None
  75. None
  76. None
  77. None
  78. None
  79. None
  80. None
  81. ! Github Repo:! http://github.com/t7/style-guide-example! ! Slides:! http://j.mp/node-style-guide! ! Mundi Morgado!

    @mundizzle! ! Nathan Smith! @nathansmith