Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

Nathan Smith

October 20, 2015
Tweet

More Decks by Nathan Smith

Other Decks in Programming

Transcript

  1. ‹#›
    © 2015 T7
    July 24, 2015
    October 20, 2015
    Node.js and
    Style Guides

    View Slide

  2. Nathan Smith!
    Principal Front-End
    Architect
    Mundi Morgado!
    Director of Front-End
    Architecture
    Introductions

    View Slide

  3. !
    Github Repo:!
    http://github.com/t7/style-guide-example!
    !
    Slides:!
    http://j.mp/node-style-guide!
    !
    Mundi Morgado!
    @mundizzle!
    !
    Nathan Smith!
    @nathansmith

    View Slide

  4. !
    TandemSeven!
    Developers :)
    !

    View Slide

  5. We Begin with a Simple Assumption…!
    !
    People are not mind readers. We are visual in
    nature. We tend not to follow instructions well.

    View Slide

  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.)

    View Slide

  7. We Enjoy Knowing the "Why" of Design

    View Slide

  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! :)

    View Slide

  9. What Is a!
    Style Guide?

    View Slide

  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.")

    View Slide

  11. No More One Offs

    View Slide

  12. Managing Expectations!
    !
    !
    “The movie opens
    with a gentleman in
    a jacket, sporting
    a mustache…”

    View Slide

  13. Managing Expectations: Perception

    View Slide

  14. Managing Expectations: Perception vs. Reality

    View Slide

  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.

    View Slide

  16. View Slide

  17. View Slide

  18. Really, your
    style guide
    can contain
    anything! :)
    http://thosewhowanderblog.com/2013/01/15/bus2alps-loves-chuck-norris/

    View Slide

  19. Examples of!
    Style Guides

    View Slide

  20. View Slide

  21. View Slide

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

    View Slide

  23. View Slide

  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.

    View Slide

  25. http://legoquestkids.blogspot.com/2011/02/30-pieces-quest-34.html
    One Size Does Not Fit All. Never Use Absolutes.

    View Slide

  26. View Slide

  27. View Slide

  28. View Slide

  29. View Slide

  30. View Slide

  31. View Slide

  32. View Slide

  33. Or, You Could Always Just

    View Slide

  34. Rolling Your!
    Own Framework

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  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

    View Slide

  39. (Nathan handled this idea gracefully, of course.)

    View Slide

  40. October 1st, 2015!
    !
    We officially started cranking on the new style guide.
    (╯°□°)╯︵ ┻━┻

    View Slide

  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.

    View Slide

  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.

    View Slide

  43. Used in Both v1 and v2
    • Lodash.js: data manipulation.!
    • Glob: file/directory globbing.!
    • FS-Extra: file system utilities.!
    • PhantomJS: for screenshots.

    View Slide

  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.

    View Slide

  45. Using NPM!
    and Webpack

    View Slide

  46. View Slide

  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"
    }
    }

    View Slide

  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"
    }
    }

    View Slide

  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"
    }
    }

    View Slide

  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"
    }
    }

    View Slide

  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"
    }
    }

    View Slide

  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.

    View Slide

  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

    View Slide

  54. Example of Trash-CLI
    !
    // Before.
    {"clean": "rm -r ./build"}
    !
    !
    // After.
    {"clean": "trash ./build"}

    View Slide

  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.

    View Slide

  56. Using ES6!
    and React

    View Slide

  57. View Slide

  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.

    View Slide

  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.

    View Slide

  60. View Slide

  61. View Slide

  62. View Slide

  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.

    View Slide

  64. View Slide

  65. Using PhantomJS to!
    Create Screenshots

    View Slide

  66. View Slide

  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.

    View Slide

  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

    View Slide

  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).

    View Slide

  70. PhantomJS Pro Tip™!
    !
    We are adding 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 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.

    View Slide

  71. View Slide

  72. View Slide

  73. Okay, Let's Dig!
    Into This Demo

    View Slide

  74. View Slide

  75. View Slide

  76. View Slide

  77. View Slide

  78. View Slide

  79. View Slide

  80. View Slide

  81. !
    Github Repo:!
    http://github.com/t7/style-guide-example!
    !
    Slides:!
    http://j.mp/node-style-guide!
    !
    Mundi Morgado!
    @mundizzle!
    !
    Nathan Smith!
    @nathansmith

    View Slide