Add recommendation of adoption, documentation and template for vanill…

…a JavaScript development stack (#214) * Stash working draft of little sites documentation * Expand assessment, add docs and template for vanilla JS * Reorganize stack docs * Add commentary on demos, massage language * Add missing word * Add links to Budget Oak Park and GitHub pages
datamade · Oct 22, 2021 · e942c24 · e942c24
1 parent bd8d5e0
commit e942c24
Show file tree

Hide file tree

Showing 16 changed files with 411 additions and 8 deletions.
diff --git a/docker/templates/new-vanilla-js-app/cookiecutter.json b/docker/templates/new-vanilla-js-app/cookiecutter.json
@@ -0,0 +1,6 @@
+{
+    "directory_name": "my-javascript-app",
+    "app_name": "my-javascript-app",
+    "app_verbose_name": "My JavaScript app",
+    "app_description": "A JavaScript app"
+}
diff --git a/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/.gitignore b/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/.gitignore
@@ -0,0 +1 @@
+node_modules/
diff --git a/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/README.md b/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/README.md
@@ -0,0 +1,49 @@
+# {{cookiecutter.app_verbose_name}}
+
+_{{cookiecutter.app_description}}_
+
+## Developing
+
+Development requires a local installation of [Yarn](https://yarnpkg.com/).
+
+Run the app:
+
+```
+yarn run develop
+```
+
+The app will be available at http://localhost:8000. 
+
+### Ensuring browser compatibility
+
+The default `babel.config.json` file will transpile JavaScript in your `js/`
+directory to syntax that's friendly to modern and legacy browsers but it will
+not transpile third-party plug-ins by default.
+
+Some plug-ins target Node versions above ES5, which means that they aren't
+compatible for older browsers. Luckily, we can tell Babel to transpile these
+dependencies to ensure our apps remain broadly compatible across browsers.
+
+To identify problematic plug-ins, you can use [the `es6-sniffer` CLI](https://github.com/hancush/python-es6-sniffer).
+
+```bash
+# Build the es6-sniffer image from GitHub
+docker build -t es6-sniffer https://github.com/hancush/python-es6-sniffer.git
+
+# Sniff out potentially incompatible modules
+docker run -v {{ cookiecutter.app_name }}_{{ cookiecutter.app_name }}-node-modules:/node_modules --rm es6-sniffer
+```
+
+Once you've found the culprits, add them to the `only` array in
+`babel.config.json`. For example:
+
+```json
+{
+    "only": [
+        "./js", // Your JavaScript - default
+        "./node_modules/problem_module_a",
+        "./node_modules/problem_module_b"
+    ],
+    // The rest of your config
+}
+```
diff --git a/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/babel.config.json b/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/babel.config.json
@@ -0,0 +1,17 @@
+{
+    "only": [
+        "./js"
+    ],
+    "presets": [
+        [
+            "@babel/preset-env", {
+                "targets": "> 0.25%, not dead",
+                "useBuiltIns": "usage",
+                "corejs": {
+                    "version": "3.8",
+                    "proposals": "true"
+                }
+            }
+        ]
+    ]
+}
diff --git a/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/css/main.css b/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/css/main.css
diff --git a/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/index.html b/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/index.html
@@ -0,0 +1,102 @@
+{% raw %}
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+    <title>{% endraw %}{{cookiecutter.app_verbose_name}}{% raw %}</title>
+
+    <meta content="Description TK" name="description" />
+    <meta content="Author TK" name="author" />
+
+    <!-- Facebook metadata -->
+    <meta property="og:site_name" content="{% endraw %}{{cookiecutter.app_verbose_name}}{% raw %}">
+    <meta property="og:type" content="website">
+    <meta property="og:title" content="Title TK">
+    <meta property="og:description" content="Description TK">
+    <meta property="og:url" content="URL TK">
+    <meta property="og:image" content="Image TK">
+
+    <!-- Twitter metadata -->
+    <meta name="twitter:card" content="summary_large_image">
+    <meta name="twitter:site" content="{% endraw %}{{cookiecutter.app_verbose_name}}{% raw %}">
+    <meta name="twitter:creator" content="Creator TK">
+    <meta name="twitter:title" content="Title TK">
+    <meta name="twitter:url" content="URL TK">
+    <meta name="twitter:description" content="Description TK">
+    <meta name="twitter:image" content="Image TK">
+
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" integrity="sha384-B0vP5xmATw1+K9KRQjQERJvTumQW0nPEzvF6L/Z6nronJ3oUOFUFpCjEUQouq2+l" crossorigin="anonymous">
+    <link href="css/main.css" rel="stylesheet">
+
+    <!-- Load fonts, if necessary -->
+    <!-- link href="https://fonts.googleapis.com/css?family=Roboto+Slab|Open+Sans:400,700&display=swap" rel="stylesheet" -->
+
+  </head>
+
+  <body>
+    <nav class="navbar navbar-expand-lg navbar-dark bg-dark pl-2 pl-md-4">
+      <div class="justify-content-left va-container">
+        <a class="navbar-brand" href="/">
+          <div id="navbar-title" class="d-inline-block">
+            <span class="d-none d-sm-inline navbar-title-text">
+              {% endraw %}{{cookiecutter.app_verbose_name}}{% raw %}
+            </span>
+          </div>
+        </a>
+      </div>
+      <div class="justify-content-right">
+        <button
+          class="navbar-toggler"
+          type="button"
+          data-toggle="collapse"
+          data-target="#navbar-supported-content"
+          aria-controls="navbar-supported-content"
+          aria-expanded="false"
+          aria-label="Toggle navigation"
+        >
+          <span class="navbar-toggler-icon"></span>
+        </button>
+      </div>
+      <div class="collapse navbar-collapse" id="navbar-supported-content">
+        <ul class="navbar-nav ml-auto">
+          <li class="nav-item">
+            <a class="nav-link" href="/">Home</a>
+          </li>
+        </ul>
+      </div>
+    </nav>
+
+    <div id="main-body">
+      <div class="mt-3 mt-lg-5 mb-5">
+        <h1>Hello, world!</h1>
+      </div>
+    </div>
+
+    <footer class="footer bg-dark text-light pt-5 pb-3">
+      <div class="container-fluid text-center">
+        <h3 class="mb-1">
+          {% endraw %}{{cookiecutter.app_verbose_name}}{% raw %}
+        </h3>
+        <p>
+        <p class="mt-3">
+          Website by <a href="https://datamade.us" target="_blank">DataMade</a>
+        </p>
+      </div>
+    </footer>
+
+    <script src="https://code.jquery.com/jquery-3.6.0.slim.min.js" integrity="sha256-u7e5khyithlIdTpu22PHhENmPcRdFiHRjhAuHcs05RI=" crossorigin="anonymous"></script>
+    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" integrity="sha384-Piv4xVNRyMGpqkS2by6br4gNJ7DXjqk09RmUpJ8jgGtD7zP9yug3goQfGII0yAns" crossorigin="anonymous"></script>
+    <script src="js/bundle.js"></script>
+
+    <!-- Load Google Tag Manager for analytics (no-op until APIKEY is set) -->
+    <script async src="https://www.googletagmanager.com/gtag/js?id=APIKEY"></script>
+    <script>
+      window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+      gtag('config', 'APIKEY');
+    </script>
+  </body>
+</html>{% endraw %}
diff --git a/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/js/main.js b/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/js/main.js
@@ -0,0 +1,2 @@
+let foo = 'bar';
+console.log(foo);
diff --git a/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/package.json b/docker/templates/new-vanilla-js-app/{{cookiecutter.directory_name}}/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "{{cookiecutter.app_name}}",
+  "author": "DataMade <[email protected]>",
+  "version": "0.0.0",
+  "description": "{{cookiecutter.app_description}}",
+  "dependencies": {
+    "@babel/core": "^7.14.6",
+    "@babel/preset-env": "^7.14.7",
+    "babelify": "^10.0.0",
+    "browserify": "^17.0.0",
+    "core-js": "^3.15.2",
+    "watchify": "^4.0.0"
+  },
+  "scripts": {
+    "develop": "yarn install && (watchify -t [ babelify --global ] js/main.js -o js/bundle.js & python3 -m http.server)",
+    "build": "yarn install && browserify -t [ babelify --global ] js/main.js -o js/bundle.js"
+  },
+  "license": "MIT"
+}
diff --git a/javascript/README.md b/javascript/README.md
@@ -0,0 +1,10 @@
+# Docker
+
+This directory records best practices for working with [JavaScript].
+
+## Contents
+
+- [Stack](stack.md)
+- Static Sites
+    - [Vanilla JavaScript](static-sites-in-vanilla-js.md)
+    - [Gatsby](gatsby/)
diff --git a/gatsby/README.md → javascript/gatsby/README.md b/gatsby/README.md → javascript/gatsby/README.md
diff --git a/gatsby/best-practices.md → javascript/gatsby/best-practices.md b/gatsby/best-practices.md → javascript/gatsby/best-practices.md
diff --git a/gatsby/recharts.md → javascript/gatsby/recharts.md b/gatsby/recharts.md → javascript/gatsby/recharts.md
diff --git a/...search/comparisons-with-existing-tools.md → ...search/comparisons-with-existing-tools.md b/...search/comparisons-with-existing-tools.md → ...search/comparisons-with-existing-tools.md
diff --git a/...by/research/recommendation-of-adoption.md → ...by/research/recommendation-of-adoption.md b/...by/research/recommendation-of-adoption.md → ...by/research/recommendation-of-adoption.md
diff --git a/gatsby/stack.md → javascript/stack.md b/gatsby/stack.md → javascript/stack.md
@@ -1,23 +1,53 @@
-# The DataMade Gatsby Stack
+# The DataMade JavaScript Stack
 
-A number of tools comprise our development stack for Gatsby project. They are:
+A number of tools comprise our development stack for projects written in or
+containing JavaScript.
 
-1. [Gatsby](https://www.gatsbyjs.org/) (obviously) - static site generator
+## Static sites
+
+### Vanilla JavaScript
+
+1. [ES6](http://es6-features.org/) - A number of big improvements to core JavaScript syntax
+2. [Yarn](https://yarnpkg.com/) - package manager
+3. [Browserify](https://browserify.org/) - build tool to bundle dependencies with code
+4. [Babelify](https://www.npmjs.com/package/babelify) - Browserify plug-in that transpiles ES6 to ES5 for browser compatibility using [Babel](https://babeljs.io/)
+5. [Watchify](https://www.npmjs.com/package/watchify) - build tool to update bundled/transpiled code during development
+6. [GitHub Pages](https://pages.github.com/) or [Netlify](https://www.netlify.com/) - deployment platforms
+
+### Gatsby 
+
+1. [Gatsby](https://www.gatsbyjs.org/) - static site generator
 2. [React](https://reactjs.org/) - JavaScript framework for building user interfaces
-3. [Node.js](https://nodejs.org/en/) / [npm](https://www.npmjs.com/) - runtime environment (run JavaScript outside of a browser) and bundled package manager
-4. [Yarn](https://yarnpkg.com/) - package manager
-5. [ESLint](https://eslint.org/) - linter
+3. [Yarn](https://yarnpkg.com/) - package manager
+4. [ESLint](https://eslint.org/) - linter
 5. [Netlify](https://www.netlify.com/) - deployment platform
 6. [Docker](https://www.docker.com/products/docker-desktop) / [Docker Compose](https://docs.docker.com/compose/) - container engine
 
+## Django/React Integration
+
+1. [ES6](http://es6-features.org/) - A number of big improvements to core JavaScript syntax
+2. [React](https://reactjs.org/) - JavaScript framework for building user interfaces
+3. [Yarn](https://yarnpkg.com/) - package manager
+4. [Browserify](https://browserify.org/) - build tool to bundle dependencies with code
+5. [Babelify](https://www.npmjs.com/package/babelify) - Browserify plug-in that transpiles ES6 to ES5 for browser compatibility using [Babel](https://babeljs.io/)
+
 ## Some example setups
 
-Building a Gatsby project? Check out these projects from the DataMade team for example architecture and component design patterns.
+### Vanilla JavaScript
+
+- Buildless: [IHS Displacement Risk Map](https://github.com/datamade/ihs-displacement-risk-in-chicago)
+- Bundled code and dependencies: [NWSS Demo Site](https://github.com/datamade/nwss-data-standard)
+
+### Gatsby
 
 - Basic static app: [`static-app-template`](https://github.com/datamade/static-app-template/) (to be iterated upon)
 - Static app with `recharts` charts: [`how-to-recharts`](https://github.com/datamade/how-to-recharts/)
 - Static app with `react-leaflet` map: [`lisc-cnda-map`](https://github.com/datamade/lisc-cnda-map/)
 
+## React in Django
+
+Integrating React with Django? See [the docs on our approach](https://github.com/datamade/how-to/blob/master/django/django-react-integration.md).
+
 ## Managing packages and plugins
 
 As in Python, there are a few competing package managers in JavaScript. The two most popular are [npm](https://www.npmjs.com/get-npm), which comes bundled with Node.js, and [Yarn](https://yarnpkg.com/). At DataMade, we like Yarn, in particular for its build speed.
@@ -38,7 +68,7 @@ error Command "yarn" not found.
 info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
 ```
 
-\- this is almost certainly the problem! Run your commands like this, instead:
+- this is almost certainly the problem! Run your commands like this, instead:
 
 ```bash
 # The application's entry point is "yarn" so we only need to pass the "add" command.