• Stars
    star
    428
  • Rank 101,481 (Top 2 %)
  • Language LiveScript
  • License
    MIT License
  • Created almost 11 years ago
  • Updated almost 7 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

node.js application archive - create self-contained binary like executable applications that are ready to ship and run

nar Build Status NPM version Total Downloads

Idiomatic application packager utility for node.js to create self-contained executable applications that are ready-to-ship-and-run.

nar provides built-in support for creating, extracting, installing and running applications easily from a simple configuration through a featured command-line interface or evented programmatic API.

To get started, see the features, basic usage or read the FAQs.

Deprecation notice: nar is not longer actively maintained, so I'd encourage you to use pkg instead, which is pretty much the same, but better.

Features

  • Simple and featured command-line interface
  • Simple evented programmatic API
  • Fully configurable from package.json
  • Supports pre/post run hooks (based on npm scripts)
  • Able to download and run archives from remote servers
  • Able to install archives from local and remote servers (like npm does)
  • Able to embed global dependencies
  • Able to embed dependencies by type
  • Able to embed node/io.js binary, also supporting multiple versions
  • Able to install archives like npm does
  • Able to create archives like raw binaries (fully self-contained)
  • Integrable in your development workflow through Grunt or Gulp
  • Uses tarball bitstream with gzip compression/decompression
  • Transparent file checksum integrity verification
  • Well tested (+270)

Contents

Installation

npm install -g nar

If you want to use the programmatic API, install it as direct package dependency

npm install nar --save[-dev]

Basic usage

Creating a new archive (reading metadata from package.json)

nar create

Extracting archive files

nar extract app-0.1.0.nar

Running an application archive

nar run app-0.1.0.nar

Installing nar archive (default to node_modules)

nar install app-0.1.0.nar --save[-dev]

Installing from remote server is also supported

nar install http://server.net/app-0.1.0.nar --save[-dev]

Executables

nar also provides support for creating executables binary-like archives which has node/io.js binary embedded, and therefore, is not required to have it already installed in the target OS

This is a useful feature when you need to deploy or test node applications in fresh or isolated servers

Create the executable:

nar create --executable
> Creates: myapp-0.1.0-linux-x64.nar

Then you can run it as simple as:

chmod +x myapp-0.1.0-linux-x64.nar
./myapp-0.1.0-linux-x64.nar start --args-start='--port 8080 --env dev'

If you need to pass custom arguments to your application, instead of use the --args-start flag, you could use the exec command directly

./myapp-0.1.0-linux-x64.nar exec --port 8080 --env dev

You can also embed a custom node binary per platform, processor architecture and version

nar create --executable --os darwin --arch x64 --node 0.12.0
nar create --executable --os darwin --arch x64 --io 1.1.0

Supported platforms:

  • linux (x86, x64, armv7l)
  • darwin (x86, x64, armv7l)
  • sunos (x86, x64, armv7l)

Note: armv7l is only available in io.js and linux platform

Supported node versions:

  • 0.8.x
  • 0.9.x
  • 0.10.x
  • 0.11.x
  • 0.12.x
  • 4.x
  • 5.x
  • 6.x

Supported io.js versions:

  • 1.x
  • 2.x
  • 3.x

Help: you can build and distribute nar executables with auto installer using the installer script

Configuration

Example package.json with full configuration

{
  "name": "my-package",
  "version": "1.0.0",
  "archive": {
    "dependencies": true,
    "devDependencies": false,
    "globalDependencies": ["npm", "bower", "http-server"],
    "patterns": ["**", "!test/**"]
  },
  "scripts": {
    "start": "node app --env ${ENV}"
  },
  "dependencies": {
    "some": "~0.1.0"
  }
}

Options

Following options can be declared in your application package.json as properties members of the archive object

dependencies

Type: boolean Default: true

Include runtime dependencies in the archive, loaded from package.json

devDependencies

Type: boolean Default: false

Include development dependencies in the archive, loaded from package.json

peerDependencies

Type: boolean Default: true

Include peer dependencies in the archive, loaded from package.json

globalDependencies

Type: array Default: null

Include global dependencies in the archive. It should define an array of strings with packages names

nar will resolve global installed packages (via requireg) and will add them to the archive

Global dependencies will be placed in .node/lib/node on archive extraction and them will be available both via require and PATH environment variable (for binary files)

binary

Type: boolean Default: false

Include the node binary in the nar archive. This is useful when you want to deploy a fully self-contained application which works in a sandboxed runtime environment

The included node binary will be, by default, the same as the used when your create the archive (taken from process.execPath)

Hooks scripts that requires node will use the self-contained binary inside the archive. It will be accessible via PATH environment variable. If you want to use node from package.json hook scripts, you could simply use: node script.js

Note: the node binary is OS and platform specific. Take this into account if you are going to deploy the archive in multiple platforms

binaryPath

Type: string Default: process.execPath

Custom node binary path to add into the archive

You must define the binary option as true in order to apply this. You can use interpolated environment variables expressions in this option, like ${HOME}/binaries/node

Aditionally, you can also define the binaryPath value from the NAR_BINARY environment variable

ignoreFiles

Type: boolean Default: true

Enable/disable ignore-like files processing in order to load files patterns to discard from the archive

patterns

Type: array Default: ['**']

Glob patterns for matching files to include or exclude in the archive. OS level specific hidden files such as .DS_Store or Thumbs.db will be ignored by default

Aditionally, nar will ignore matched patterns defined in ignore-like files

Hooks

nar supports application pre/post execution hooks, that are also supported by npm

You should define them from package.json in the scripts member (see npm scripts)

Supported hooks (by execution order):

  • prestart
  • start
  • stop
  • poststop

Configuration example:

{
  "name": "app",
  "version": "1.0.0",
  "scripts": {
    "prestart": "mkdir -p temp/logs",
    "start": "node app --env ${ENV}",
    "stop": "rm -rf cache"
  }
}

Aditional useful features

Environment variables in hook commands

You can consum environment variables from hook comands using the ${VARNAME} notation

Nar-specific execution environment

nar will expose the NODE_NAR environment variable in the hooks execution contexts and node application

You can make any environment runtime checks if your application needs a different behavior dependending of the runtime environment

Ignoring files

nar will find ignore-like files in order to load and match patterns of files to discard

Supported files by priority are (the first one found implies to ignore other ones):

  • .narignore
  • .buildignore
  • .npmignore
  • .gitignore

Command-line interface

Usage: nar [options] [command]

Commands:

  help
    Output usage information
  create [options] [path]
    Create a nar archive
  extract [options] <archive>
    Extract archive
  run [options] <archive>
    Run archive files
  list [options] <archive>
    List archive files
  install [options] <archive>
    Install archive
  get [options] <url>
    Download archive from HTTP server

Options:

  -h, --help     output usage information
  -V, --version  output the version number

Usage examples:

  $ nar create
  $ nar run app.nar
  $ nar extract app.nar -o some/dir
  $ nar list app.nar
  $ nar install app.nar --save
  $ nar get http://server.net/app.nar

Command specific help:

  $ nar <command> --help

create

Alias: c build

Create a new archive from an existent application

$ nar create
$ nar create some/path --debug
$ nar create path/to/package.json -o some/dir
$ nar create --dev-dependencies --global-dependencies 'npm, grunt-cli'
$ nar create --omit-dependencies
$ nar create --verbose
$ nar create --executable

extract

Alias: e

Extract archive files into directory

$ nar extract
$ nar extract app.nar
$ nar extract app.nar -o some-dir
$ nar extract app.nar --debug

run

Alias: x start

Run nar archive application

$ nar run app.nar
$ nar run app.nar --no-hooks
$ nar run app.nar --no-clean --debug
$ nar run app.nar --verbose
$ nar run app.nar --args-start '--env ${ENV}'
$ nar run app.nar --args-stop '--path ${PATH}'
$ nar run http://server.net/app.nar

install

Alias: i

Install nar archive as dependency (defaults to node_modules)

$ nar install app.nar --save
$ nar install app.nar -o some/dir --save-dev
$ nar install app.nar --debug
$ nar install http://server.net/app-0.1.0.nar
$ nar install -g http://server.net/app-0.1.0.nar

get

Alias: g download

Download a remote archive

$ nar get http://server.net/app.nar
$ nar get http://server.net/app.nar --user john --password pa$s
$ nar get http://server.net/app.nar --proxy http://proxy:3128
$ nar get http://server.net/app.nar --strict-ssl --timeout 60000

list

Alias: l show

List files from archive

$ nar list app.nar
$ nar list app.nar --no-table

Programmatic API

nar provides a full featured programmatic API designed to easy to use from other node applications

The API is full asynchronous event based

var nar = require('nar')

var options = {
  path: 'my/package.json', // defaults to ./package.json
  dest: 'build/', // defaults to current directory
  binary: true, // embed node binary to use it when run the archive
  dependencies: true, // embed dependencies declared in package.json
  devDependencies: true, // the same for dev dependencies
  globalDependencies: ['npm', 'grunt-cli'] // and for globals :)
}

nar.create(options)
  .on('error', function (err) {
    throw err
  })
  .on('info', function (nar) {
    console.log(nar.name)
  })
  .on('entry', function (file) {
    console.log('Adding file:', file.name)
  })
  .on('end', function (path) {
    console.log('Archive created in:', path)
  })

nar.create(options)

Fired events: end, error, entry, archive, message, info, start

Create new archive based a the given package.json and additional defined options

Options

You can pass any configuration options and the following options:

  • path string Path to package.json or application directory. Required
  • dest string Extract destination path. Default to random temporal directory
  • file string Archive file name. Default to package name + version, taken from package.json
  • patterns array List of glob patterns to match files to include or exclude. See node-glob

nar.createExec(options)

Same as nar.create(), but this generate an executable binary-like archive

Aditional executable options supported are:

  • os string Node.js OS binary platform to embed. Detault to runtime OS
  • arch string Node.js OS binary architecture to embed. Default to runtime OS arch
  • node string Node.js version to embed. Default to the current node runtime version

nar.extract(options)

Fired events: end, error, entry, archive, message, info, start

Extract archive files into an output directory

Options
  • path string Path to nar archive. Required
  • dest string Extract destination path. Default to random temporal directory
  • tmpdir string Temporal directory to use. Default to random temporal directory

nar.run(options)

Fired events: end, error, entry, archive, command, info, start, stdout, stderr, exit

Read, extract and run an application. It will read command scripts hooks in package.json

Options
  • path string Path to nar archive. Required
  • dest string Extract destination path. Defaults to random temporal directory
  • args object Aditional argument to pass to hooks. Keys must have the same hook name
  • hooks boolean Enable/disable run command hooks. Defaults to true
  • clean boolean Clean app directory on exit. Defaults to true

nar.list(options)

Options: path

Fired events: end, error, entry

Read and parse a given .nar archive, emitting the entry event for each existent file

Options
  • path string Path to nar archive. Required

nar.install(options)

Fired events: end, download, downloadEnd, error, entry, start, progress

Install archive as dependency in node_modules directory. It can aditionally download the archive from remote server

Options
  • path string Path to nar archive. Required if url is empty
  • url string URL to download the archive. Required if path is empty
  • filename string Downloaded filename. Defaults taken from URI path
  • dest string Install destination path. Defaults to random node_modules
  • clean boolean Clean downloaded archive after install. Defaults to true
  • proxy string Proxy server URL. Default taken from environment variable http_proxy
  • auth object user and password for HTTP basic authentication
  • timeout number HTTP request timeout in ms. Defaults to 10000
  • headers object Define aditional HTTP request headers
  • strictSSL boolean Performs HTTP request with valid SSL servers. Defaults to false
  • save boolean Save installed package as runtime dependency in package.json. Default to false
  • saveDev boolean Save installed package as development dependency in package.json. Default to false
  • savePeer boolean Save installed package as peer dependency in package.json. Default to false
  • global boolean Install package as global dependency. Default to false

nar.get(options)

Alias: download

Fired events: end, error, download, progress

Download archive from remote server. It supports basic HTTP authentication and proxy

Options
  • path string Path to nar archive. Required if url is empty
  • url string URL to download the archive. Required if path is empty
  • dest string Install destination path. Defaults to random node_modules
  • filename string Downloaded filename. Defaults taken from URI path
  • clean boolean Clean downloaded archive after install. Defaults to true
  • proxy string Proxy server URL. Default taken from environment variable http_proxy
  • auth object user and password for HTTP basic authentication
  • timeout number HTTP request timeout in ms. Defaults to 10000
  • strictSSL boolean Performs HTTP request with valid SSL servers. Defaults to false

nar.VERSION

Type: string

Events

Complete list of available events for subscription

  • end ([result]) Task was completed successfully
  • error (error) Some error happens and task cannot be completed
  • entry (entry) On read/write file, usually fired from file streams
  • archive (archive) Emit the archive that is being processed
  • message (message) General information status message, useful for debugging purposes
  • download () Starts a download process
  • command (command) Hook command to execute when run an application
  • info (config) Expose the nar archive config
  • start (command) On application start hook command
  • stdout (string) Command execution stdout entry. Emits on every chunk of data
  • stderr (string) Command execution stderr entry. Emits on every chunk of data
  • exit (code, hook) When a hook command process ends

FAQ

Which kind of archive is nar?

nar archives are just a tarball containers with gzip compression. It's equivalent to a file with tar.gz extension, so you can extract it with tar, 7zip or file compression tools ans inspect the archive contents

Example using tar

$ tar xvfz app-0.1.0.nar

Note: this is not applied for nar executables, since they have another format and not just a tarball file interface

Is required to have installed node or nar in order to work with nar archives?

No. From version 0.3.0 you can create executable binary-like applications containers and there is no more required to have previously installed node or nar in order to run, install or extract an application

You can create an executable archive simply passing a flag

$ nar create --executable

Then you could run it like a binary:

$ ./app-0.1.0-linux-x64.nar [run|extract|install] [options]

If you don't create your archive with this option, you must to have nar (and consequently node) installed in the target computer

nar executables runs in Windows?

No. nar executables only can run in POSIX operative systems (GNU/Linux, Darwin or SunOS)

Is not planned to support it due to technical limitations in Windows OS

There is the maximum file size for nar archives?

V8 JavaScript engine (which node uses) has a heap memory limit of 1 GB. This is teorically the maximum fize limit, however, it can variadic depend on the number of files and its sizes, and also based on your machine memory resources and OS (if you are running Windows) when creating, running or extracting nar archives

However, nar was tested in real projects creating archives which contains thousands of files and which the generated archive has more than 100 MB of file size

Which binary is used in nar executables?

The node binary that is begin used when the nar archive is created

To be exactly, the binary that process.execPath points to

That means, if you create an executable archive in OSX and then deploy it into a GNU/Linux server, it will fail. If you want to create a nar archive for different OS, you must create a nar executable passing the target OS and, optionally, the processor architecture or node.js version, like this:

nar create --executable --os linux --arch x64 --node 0.11.9
When will be used embedded node binary in the archive?

When you use the run command, if the archive you are running has a node binary embedded and therefore it was created with the binary option set true, your application will use it transparently

Which MIME type is recommened to serve nar files?

One of the following types will be valid:

  • application/x-gzip
  • application/x-compress
  • application/x-compressed
  • application/octet-stream
Can I download archives which requires server authentication?

Of course. You could use both methods:

Passing credentials via optional flags:

$ nar get https://server.net/archive.nar --user john --password p@s$

Or using the HTTP_USER and HTTP_PASSWORD environment variables

$ HTTP_USER=john HTTP_PASSWORD=p@s$ nar get https://server.net/archive.nar

Contributing

Wanna help? Cool! It will be really apreciated :)

nar is completely written in LiveScript language. Take a look to the language documentation if you are new with it. and follow the LiveScript language conventions defined in the coding style guide

You must add new test cases for any new feature or refactor you do, always following the same design/code patterns that already exist

Development

Only node.js is required for development

Clone/fork this repository

$ git clone https://github.com/h2non/nar.git && cd nar

Install dependencies

$ npm install

Compile code

$ make compile

Run tests

$ make test

Publish a new version

$ make publish

License

MIT © Tomas Aparicio

More Repositories

1

imaginary

Fast, simple, scalable, Docker-ready HTTP microservice for high-level image processing
Go
5,543
star
2

toxy

Hackable HTTP proxy for resiliency testing and simulated network conditions
JavaScript
2,733
star
3

bimg

Go package for fast high-level image processing powered by libvips C library
Go
2,683
star
4

filetype

Fast, dependency-free Go package to infer binary file types based on the magic numbers header signature
Go
2,076
star
5

gock

HTTP traffic mocking and testing made easy in Go ༼ʘ̚ل͜ʘ̚༽
Go
2,067
star
6

gentleman

Plugin-driven, extensible HTTP client toolkit for Go
Go
1,072
star
7

videoshow

Simple node.js utility to create video slideshows from images with optional audio and visual effects using ffmpeg
JavaScript
873
star
8

baloo

Expressive end-to-end HTTP API testing made easy in Go
Go
776
star
9

jshashes

Fast and dependency-free cryptographic hashing library for node.js and browsers (supports MD5, SHA1, SHA256, SHA512, RIPEMD, HMAC)
JavaScript
698
star
10

filetype.py

Small, dependency-free, fast Python package to infer binary file types checking the magic numbers signature
Python
642
star
11

rocky

Full-featured, middleware-oriented, programmatic HTTP and WebSocket proxy for node.js (deprecated)
JavaScript
371
star
12

pook

HTTP traffic mocking and testing made easy in Python
Python
329
star
13

paco

Small utility library for coroutine-driven asynchronous generic programming in Python
Python
202
star
14

semver.c

Semantic version in ANSI C
C
185
star
15

riprova

Versatile async-friendly retry package with multiple backoff strategies
Python
116
star
16

node-imaginary

Minimalist node.js command-line & programmatic API client for imaginary
JavaScript
106
star
17

youtube-video-api

Simplified programmatic and command-line interface for YouTube Video API. Built for node.js
JavaScript
67
star
18

siringa

Minimalist dependency injection library for Python that embraces type annotations syntax
Hy
54
star
19

audioconcat

Tiny node.js module to concat multiple audio files using ffmpeg
JavaScript
45
star
20

requireg

Resolve and require local & global modules in node.js like a boss
JavaScript
45
star
21

thread.js

Frictionless library to deal with multithread programming in the browser
JavaScript
41
star
22

grunt-stubby

Grunt task to setup a stub/mock server based on JSON/YAML/JS configuration files
JavaScript
26
star
23

hu

Small, generic functional helper library for node.js and browsers
wisp
20
star
24

gentleman-consul

Gentleman's plugin for Consul server discovery and optional configurable retry/backoff policies
Go
19
star
25

nightmare-google-oauth2

Nightmare plugin to retrieve a Google APIs OAuth2 token. Useful for server-to-server automation
JavaScript
19
star
26

balboa

Simple HTTP forward proxy
JavaScript
16
star
27

domlight

Spotlight DOM elements easily
JavaScript
16
star
28

resizr

Dead simple HTTP service written in Go for fast and easy image resizing from remote URLs
Go
16
star
29

google-oauth2-token

No headaches. Automation wins. Get a fresh OAuth2 token for Google APIs in just one command
JavaScript
16
star
30

angular-thread

AngularJS primitive bindings for thread.js
JavaScript
15
star
31

resilient-consul

Resilient.js middleware to use Consul for service discovery and balancing
JavaScript
14
star
32

gentleman-mock

HTTP mocking for gentleman's clients made easy. Uses gock under the hood
Go
14
star
33

rocky-consul

Rocky middleware for service discovery and dynamic traffic balancing using Consul
JavaScript
14
star
34

angular-resilient

Use $http as a resilient, failover and client-side balanced HTTP client
JavaScript
13
star
35

go-is-svg

Check if a given buffer is a valid SVG image in Go (golang)
Go
12
star
36

node-os-shim

Native OS module API shim for older node.js versions
JavaScript
12
star
37

stream-interceptor

Intercept, modify and/or ignore chunks data and events in any readable stream
JavaScript
11
star
38

gentleman-retry

gentleman's plugin providing retry policy capabilities in your HTTP clients
Go
11
star
39

bbscraper

Simple phpBB forum thread web scraper written in Python
Python
11
star
40

Sencha-WebSocket

WebSocket client abstraction library for Sencha JavaScript frameworks (DEPRECATED)
JavaScript
10
star
41

grunt-beautiful-docs

Generate beautiful markdown-based documentation using Grunt
CoffeeScript
9
star
42

findup

Find the first file matching in a current working directory or the nearest ancestor directory up to root using Go
Go
9
star
43

resolve-tree

Recursively resolve node.js modules and its dependencies looking into node_modules trees.
JavaScript
8
star
44

http-forward

Simple one-line proxy forward for incoming HTTP requests. Built for node.js/io.js
JavaScript
7
star
45

injecty

Micro library for dependency injection and inversion of control containers in node and browsers
wisp
6
star
46

sharedworkers-angular-poc

A simple proof of concept using Shared WebWorkers + Two-way data binding in AngularJS
CSS
6
star
47

toxy-ip

toxy rule to easily filter by IP addresses (supports CIDR, subnet, IP ranges...)
JavaScript
6
star
48

fw

Tiny library for asynchronous control-flow in node and browsers
wisp
6
star
49

pipefy

Transform a function into a pipeable writable stream in node/io.js
JavaScript
5
star
50

node-bintray

CLI and programmatic interface for Bintray built for node.js
CoffeeScript
5
star
51

generator-api-service

A Yeoman generator to build an opinionated but community-driven convention-focused, general purpose, resource-oriented HTTP service in node.js
JavaScript
4
star
52

htgen

Tiny hypertext markup code generator for node and browsers
LiveScript
4
star
53

node-authrc

authrc implementation for node
CoffeeScript
4
star
54

gulp-nar

Create and extract nar archives from Gulp
JavaScript
4
star
55

ng-exam

Are you a great AngularJS developer? (wip)
JavaScript
4
star
56

oml

Minimalist template engine built-on-top of the Oli language for node and browsers
JavaScript
4
star
57

buildspec

Declarative, featured, unopiniotated, CI-agnostic build configuration file
4
star
58

OPEW

[NOT MAINTAINED] OPEW is a powerful, complete, independent and extensible open source distribution stack for GNU/Linux (64 bits) based OS. Its goal is to provides a rich portable ready-to-run development environment focused on modern and robust programming languages in oder to satisfy the common needs for the web development.
Shell
4
star
59

promitto

Tiny promise library mostly compatible with Promise/A+ spec and ES6
wisp
3
star
60

heroku-buildpack-binary-download

Download and execute POSIX compatible binaries in Heroku apps
Shell
3
star
61

grunt-nar

Create and extract nar archives from Grunt
CoffeeScript
2
star
62

ASIR

ASIR course exercises for fun and profit
Shell
2
star
63

consul-cluster-test

Consul cluster test suite
Python
2
star
64

butler

A small, elegant and friendly library to deal elegantly with Service Workers (experimental)
JavaScript
2
star
65

node-cloudimage

Minimalist node/io.js CLI & programmatic stream-based interface for Cloudimage.io
JavaScript
2
star
66

mimeware

Simple node.js/io.js HTTP middleware to infer the proper MIME content type response header
JavaScript
2
star
67

bock

Browser next-generation HTTP traffic mock and proxy interceptor using Service Worker (experimental)
JavaScript
2
star
68

OPEW-bash-installer

Bash-based installer builder utility for the OPEW project
Shell
2
star
69

findup.rs

Find the first file matching in a current working directory or the nearest ancestor directory up to root
Rust
2
star
70

http-version

HTTP API version matching strategies as middleware for connect/express/rocky
JavaScript
2
star
71

nar-installer

Simple Bash script to easily install nar executable packages. Analog to npm install --global
Shell
2
star
72

http-api-versioning

Analysis of multiple HTTP API versioning design strategies
1
star
73

midware-pool

Tiny module to create a pool of connect-style domain-agnostic middleware layers in browsers and node.js
JavaScript
1
star
74

apachelog

Simple Go net/http compatible middleware for Apache style logging
Go
1
star
75

rocky-cli

Command-line interface for rocky. Supports TOML configuration file to easily set up your proxy
JavaScript
1
star
76

carcasse

Build structured, modular and object-oriented JavaScript projects
JavaScript
1
star
77

go-memstats

Human-friendly debugger to print in stdout the memory and GC stats
Go
1
star