Copies node packages to a directory where your frontend tools will be able to find them


Keywords
frontend, dependencies, packages, copy, vendor, static, assets, javascript, npm, statics
License
MIT
Install
npm install frontend-dependencies@1.1.8

Documentation

Build Status

frontend-dependencies

Easily manage your frontend dependencies in package.json: Install node modules and copy desired files to each directory.

NOTE: There is a breaking change from Version 0.4.0 to 1.0.0. Be sure to update your projects to the new syntax!

Example

Your package.json:

{
  "name": "frontend-dependencies-test",
  "version": "1.0.0",
   // etc.

  "devDependencies": {
    "shelljs": "0.7.4"
  },
  "frontendDependencies": {
    "target": "static/",
    "packages": {
      "jquery": {
          "version": "3.1.0",
          "src": "dist/jquery.min.js"
      },
      "normalize.css": {
          "version": "4.2.0",
          "src": "normalize.css"
      }
    }
  }
}

Your target folder in your project will look like:

 project
   |
   |_ static
   |    |_ jquery.min.js
   |    |_ normalize.css
   |

Full example

{
  "name": "frontend-dependencies-test",
  "version": "1.0.0",
  "description": "frontend-dependencies test project",
  "main": "index.js",
  "author": "Matias Surdi <matias@surdi.net>",
  "license": "Apache-2.0",
  "dependencies": { },
  "devDependencies": {
    "shelljs": "0.7.4"
  },
  "frontendDependencies": {
    "target": "static/",
    "packages": {
      "jquery": {             // npm package name
          "version": "3.1.0", // for `npm install`: version, tag or version range
          "src": "dist/*"     // relative path in package to copy files
          "namespaced": true  // extra parent folder with package Name
      },
      "normalize.css": { // copy whole package
          "version": "4.2.0"
      },
      "turbolinks": {
          // alternative to 'version`: specifie git url, tarball url, tarball file, folder
          "url": "git://github.com/turbolinks/turbolinks.git",     
          "src": "{src,LICENSE}", // copy multiple files
          "target": "static/turbo" // specific target path
      }
    }
  }
}

Your target folder in your project will look like:

 project
   |
   |_ static
   |   |
   |   |_ jquery
   |   |    |_ core.js
   |   |    |_ jquery.js
   |   |    |_ jquery.min.js
   |   |    |_ ...
   |   |
   |   |_ normalize.css
   |   |    |_ CHANGELOG.md
   |   |    |_ LICENSE.md
   |   |    |_ normalize.css
   |   |    |_ ...
   |   |
   |   |_ turbo
   |        |_ src
   |        |   |_ turbolinks
   |        |
   |        |_ LICENSE
   |
   |

Installation

npm install --save frontend-dependencies

Make it a postinstall script by adding this to your package.json:

    "scripts": {
        "postinstall": "node ./node_modules/frontend-dependencies/index.js"
    }

If postinstall did not run you can use this after installed:

npm run postinstall

Run can also run it with

./node_modules/.bin/frontend-dependencies

Windows user run it in PowerShell or use this command in Command Prompt:

node_modules\.bin\frontend-dependencies.cmd

Packages Options

version

The npm package name will be taken from the name specified in "frontendDependencies.packages" and the package installed from npm.

                         // none: install latest
    "version": "0.2.4"   // version
    "version": "beta"    // tag
    "version": "^0.2.4"  // version range

url

Alternative sources for your packages.

    "url": "ssh://user@host.xz:port/path/to/repo.git/"
    "url": "git://github.com/ember-cli/ember-cli.git#v0.1.0"
    "url": "forever.tar.gz"
    "url": "https://github.com/User/repo/archive/master.tar.gz"
    "url": "/testfolder"

src

The source file(s) or folder(s) within each npm package to be copied.

   // option 1: do not specify to copy the whole folder

   // option 2: copy one file or folder
   "src": "dist/*"

   // option 3: copy serveral files or folders
   "src": "{index.js,index.css}"

target

A specific target folder to copy the files of one frontend package to. If not specified extra, the target will be "frontendDependencies.target".

   "target": "dest"

namespaced

Often you will copy just a single file from a package and copy it in your static files folder. Doing this for 4 files, you won't experience namespace errors. If you copy more files or the whole folder (= no src option defined), then you want to create a parent folder with the actual module name. Enable this with the namespace option, the default is false.

   "namespaced": true

If you do not specify a src and no namespaced option like in the example below, namespaced is set to true, to avoid namespace errors (e.g. file conflicts from two package.json).

// no `src` and `namespaced` defined
"jquery": {
   "version": "3.1.0"
},
"normalize.css": {
   "version": "4.2.0"
}
// => confilicts prevented, by parent folders with module name

Tests

npm test

ToDo

  • improve testing for npm install for packages and urls

Experience with managing npm dependencies for the frontend

Ideas

The goal of this package is to make the management of frontend components easier and lower maintenance. Aspects we consider important for "how to do it right":

  • Most packages come with a ready to use (compiled and minified, etc.) version of js and css
  • With http2, the sending of small files is encouraged
  • The browser can cache common libs easy

We think to copy the needed part of a libs to your webserver folder, is simple and gives you most benefit.

Although there is no handling of the dependencies of the frontend components (like a jQuery plugin needs jQuery), this seems not too important for small projects and also frontend packages can do this over peerDependencies.

This article is interesting: http://blog.npmjs.org/post/101775448305/npm-and-front-end-packaging