Skip to content
🐚 Project-specific configuration for the Node.js REPL
JavaScript
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
media
test
.gitignore
.npmrc
.travis.yml
CHANGELOG.md
LICENSE
README.md
cli.js
index.js
package.json

README.md

🐚 local-repl

Current Version Build Status Dependabot Status

Project-specific REPLs for Node.js. local-repl allows you to automatically import modules and values into your REPL sessions with simple configuration in your project's package.json and/or .replrc.js.

Features!

  • Automatically import modules into your REPL sessions
  • Use await in the REPL without having to wrap your code in async functions
  • Configure the banner and prompt

Add local-repl to your project

$ npm install local-repl --save-dev
# OR
$ yarn add local-repl --dev

Add the following to package.json. Note: lodash is used as an example here; it is not required to use local-repl.

{
  "scripts": {
    "repl": "local-repl"
  },
  "devDependencies": {
    "local-repl": "^3.0.0"
  },
  "dependencies": {
    "lodash": "^4.17.4"
  },
  "repl": [
    "lodash"
  ]
}

Run it

$ npm run repl

This will start a REPL session with lodash already imported.

Specifying aliases

You can pass an array of objects containing the keys "name" (required), "module" (for imports), or "value" (for values).

{
  "repl": [
    {"name": "l", "module": "lodash"},
    {"name": "meaningOfLife", "value": 42}
  ]
}

Importing local modules

Local modules can be imported, too.

{
  "repl": [
    {"name": "project", "module": "./"},
    {"name": "utils", "module": "./lib/utils"}
  ]
}

Using .replrc.js

Instead of defining configuration in "package.json", you may define your configuration in a .replrc.js file. This is useful if you want to dynamically compute modules and values for your REPLs.

// .replrc.js
const User = require('./myapp/models/User');

module.exports = {
  context: [
    'lodash',
    'myapp/utils',
    {name: 'me', value: User.getByEmail('sloria')},
  ]
}

Note: Configuration defined in .replrc.js takes precedence over configuration defined in package.json.

Defining context as an object

Context can be defined as an object rather than an array.

// .replrc.js
const User = require('./myapp/models/User');

module.exports ={
  context: {
    l: require('lodash'),
    utils: require('myapp/utils'),
    me: User.getByEmail('sloria'),
  }
}

Promises as context values

Context values that are promises will be resolved before the REPL starts.

// .replrc.js
const promise = new Promise((resolve) => {
  setTimeout(() => {
    resolve(42);
  }, 500);
});

module.exports = {
  // REPL will have meaningOfLife with value 42 in context
  context: {
    meaningOfLife: promise,
  }
};

await support

You can use await in your REPL sessions without having to create async functions.

Just add the following to your package.json:

{
  "repl": {
    "enableAwait": true
  }
}

Or in .replrc.js

// .replrc.js
module.exports = {
  enableAwait: true
}

More configuration

Configuring the prompt

In package.json:

{
  "repl": {
    "prompt": "myproject $"
  }
}

In .replrc.js:

// .replrc.js
module.exports = {
  prompt: 'myproject $'
}

You can also define prompt as a function in .replrc.js. The function will receive the REPL context and the parsed package.json object.

// .replrc.js
module.exports = {
  prompt: (context, pkg) => {
    return `${pkg.name} ${pkg.version} $`
  }
}

Configuring the banner

In package.json:

{
  "repl": {
    "banner": "Welcome to the myapp REPL. Happy hacking!"
  }
}

You can also define banner as a function in .replrc.js. The function will receive the REPL context and the parsed package.json object.

// .replrc.js
const _ = require('lodash');
const chalk = require('chalk');

module.exports = {
  context: [
    {name: 'l', value: _},
    {name: 'meaningOfLife', value: 42},
  ],
  banner: (context, pkg) => {
    console.log(chalk.bold(`Welcome to the REPL for myapp ${pkg.version}.`));
    console.log(chalk.green('Happy hacking!'));
    console.log(chalk.cyan('Context:'), _.keys(context).sort().join(', '));
  }
}

Programmatic usage

local-repl can be used programatically. The .start(options) function takes the same options as Node's built-in repl.start(options) and returns a Promise that resolves to a REPLServer instance.

const repl = require('local-repl');

repl.start({ prompt: '< -_- > ' });

Inspiration

local-repl is inspired a number of other great projects:

  • konch - REPL configuration for Python
  • n_ - Node.js REPL with lodash

License

MIT licensed. See LICENSE for more details.

You can’t perform that action at this time.