search

codeforamerica / honeycrisp-gem

A Rails gem with base styles and Javascript for Code for America products
http://honeycrisp.herokuapp.com
MIT License
26 stars 8 forks source link

Explore how to package assets for a non-Rails context #173

Closed luigi closed 4 years ago

luigi commented 4 years ago
hartsick commented 4 years ago

Additional (hopefully helpful!) context in this issue: https://github.com/codeforamerica/honeycrisp-gem/issues/100

luigi commented 4 years ago

The US Web Design System makes their code available in two forms:

  1. A downloadable ZIP archive
  2. An NPM package

The ZIP Archive is made available as a GitHub Release:

uswds-2.5.0/
├── css/
│   ├── uswds.min.css.map
│   ├── uswds.min.css
│   └── uswds.css
├── fonts/ (all web font files)
├── img/ (all images, mostly as SVGs, some PNGs)
├── js/
│   ├── uswds.min.js.map
│   ├── uswds.min.js
│   └── uswds.js
└── scss/ (all components)

The simplest usage path is to copy and paste the minified CSS and JS files into one's project.

The NPM package is installable via: npm install --save uswds@latest

Which will create a directory in node_modules of the current project.

The recommended pipeline for customizing the design system is via gulp.

luigi commented 4 years ago

Bootstrap's recommended method is to use its assets made available via a CDN:

<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css" integrity="sha384-Vkoo8x4CGsO3+Hhxv8T/Q5PaXtkKtu6ug5TOeNV6gBiFeWPGFN9MuhOf23Q9Ifjh" crossorigin="anonymous">
<script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/js/bootstrap.min.js" integrity="sha384-wfSDF2E50Y2D1uUdj0O3uMBJnjuUD4Ih7YwaYd1iqfktj0Uod8GCExl3Og8ifwB6" crossorigin="anonymous"></script>

But it also makes the code available in several other forms:

Icons are available separately, via npm package or GitHub Release archive.

luigi commented 4 years ago

Google Material Design also recommends using their assets from a CDN:

<head>
  <link href="https://unpkg.com/material-components-web@v4.0.0/dist/material-components-web.min.css" rel="stylesheet">
  <script src="https://unpkg.com/material-components-web@v4.0.0/dist/material-components-web.min.js"></script>
  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
</head>

Note that icons are made available via a Google Font.

For installing into a project, an npm package is available:

npm i material-components-web

luigi commented 4 years ago

Recommended Strategy

  1. Maintain this repository as the source of truth, keeping its Rails-specific context.
  2. Add a pipeline to build CSS, JS, font, and image assets into a /dist top-level directory, which would contain both minified and non-minified versions of (S)CSS and JS. The non-minified SCSS could be modularized to allow users to pick certain components for their project.
  3. The /dist directory can then be used in packaging GitHub Release archives. This would be the first new distribution format.
  4. Use the contents of the /dist directory to create an npm module, so that npm install honeycrisp will install a package in a JS project. This is the second new distribution format.
  5. Use the npm module to host assets on a CDN, specifically https://www.jsdelivr.com/ which auto-mirrors contents of npm modules. This is the third new distribution format.

Distribution Formats

CDN:

<head>
  <link href="https://cdn.jsdelivr.net/npm/honeycrisp@1.00/dist/honeycrisp.min.css" rel="stylesheet">
  <script src="https://cdn.jsdelivr.net/npm/honeycrisp@1.00/dist/honeycrisp.min.js"></script>
</head>

Download ZIP archive:

https://github.com/codeforamerica/honeycrisp/releases/download/v1.0.0/honeycrisp-1.0.0.zip

NPM:

$ npm i honeycrisp

Ruby:

$ gem install honeycrisp
lkogler commented 4 years ago

This looks like a good plan to me. Thanks for the clear and thorough write up!

bensheldon commented 4 years ago

I think this is a great proposal! I have some non-blocking suggestions:

luigi commented 4 years ago

Closing in favor of #176.