Skip to content
Memento is a development-only tool that caches HTTP calls once they have been executed.
TypeScript JavaScript
Branch: master
Clone or download
dependabot-preview and antoinechalifour chore(deps): bump koa from 2.8.2 to 2.10.0 (#105)
Bumps [koa](https://github.com/koajs/koa) from 2.8.2 to 2.10.0.
- [Release notes](https://github.com/koajs/koa/releases)
- [Changelog](https://github.com/koajs/koa/blob/master/History.md)
- [Commits](koajs/koa@2.8.2...2.10.0)

Signed-off-by: dependabot-preview[bot] <support@dependabot.com>
Latest commit b4b5aa1 Oct 19, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin feat: add config reloading command (#58) Sep 2, 2019
doc
examples doc: update examples Sep 8, 2019
src feat: support imports using the user editor (#77) Sep 13, 2019
tests/integration
.eslintrc chore(eslint): allow explicit any Aug 15, 2019
.gitignore feat: support imports using the user editor (#77) Sep 13, 2019
.nvmrc chore: setup travis Aug 13, 2019
.release-it.json chore: setup release-it Aug 21, 2019
.travis.yml
CHANGELOG.md Release 1.6.0 Oct 3, 2019
LICENSE feat: add file adapter for caching responses Aug 14, 2019
README.md feat: support imports using the user editor (#77) Sep 13, 2019
cover.png doc: update CLI description Sep 8, 2019
package-lock.json chore(deps): bump koa from 2.8.2 to 2.10.0 (#105) Oct 19, 2019
package.json chore(deps): bump koa from 2.8.2 to 2.10.0 (#105) Oct 19, 2019
tsconfig.json feat: display memento version in CLI Aug 20, 2019
yarn.lock chore(deps): bump koa from 2.8.2 to 2.10.0 (#105) Oct 19, 2019

README.md

Build Status codecov

Memento

Memento is a development-only tool that caches HTTP calls once they have been executed

Memento screenshot

Why should one use Memento?

When building a UI or working on any project that rely on external services, some things can slow us down:

  • the API may not be stable at the moment
  • the API may apply harsh rate-limiting (and that's terrible if you forget the dependency array in your React.useEffect 😉)
  • ...or you may be working on a train or plane where the network is not reliable.

Memento has been built to solve these problems.

Memento acts as a development buddy that remembers the requests that your application is sending, the server response, and will respond to your app without the need for requests to go over the internet.

Pro-tip: Memento may also be used for stubbing external services for integration or end-to-end testing 🎉

Getting started

1. Add a Memento configuration file

To add Memento to your project, you need to add a .mementorc file to your project root.

Note: you may use any other configuration file supported by cosmiconfig.

The most basic configuration file to cache the PunkApi would look something like this:

{
  "targetUrl": "https://api.punkapi.com/v2"
}

2. Target the endpoint

You will then need to configure your app to target http://localhost:3344 as the API url.

Note: this should only be done at development time, do not target localhost for your production build!

3. Run Memento

You can then run Memento using npx @antoinechalifour/memento.

Note: npx is a command that comes with npm when installing Node and enables users to run binaries without installing them manually.

Options

The following options are supported:

Option Description Example Default value
targetUrl The API base URL http://localhost:4000 None
port The port used to launch Memento 9876 3344
cacheDirectory The cache directory used for storing responses memento-integration .memento-cache
useRealResponseTime Whether Memento should respond using the actual response time true false
disableCachingPatterns An array of patterns used to ignore caching certain requests [{ method: 'post', urlPattern: '/pokemon/*/sprites' }] []
ignoreCookiesPattern A regular expression for ignoring cookies AMP_TOKEN|_ga.*|_gid null

Option: disableCachingPatterns

You may use disableCachingPatterns in your configuration to tell Memento to ignore caching responses based on the request method and URL. As an example, if you wish to not cache routes likes /pokemon/mew/abilities and pokemon/ditto/abilities, you may use the following configuration :

{
  // ... your configuration
  "disableCachingPatterns": [{
    "method": "GET",
    "urlPattern": "/pokemon/*/abilities"
  }]
}

The minimatch package is used for comparing glob patterns and the actual url. You may use a tool like globtester to test your configurations.

Recipe: ignore caching all POST requests

{
  // ... your configuration
  "disableCachingPatterns": [{
    "method": "post",
    "urlPattern": "**"
  }]
}

Option: ignoreCookiesPattern

Even though Memento play well with stateless APIs, you may want to use it against APIs which use cookies. This might be tricky if the server always sets different cookies (thus cached requests cannot be replayed as the change every time they are made).

Memento provides an ignoreCookiesPattern which allows you to tell Memento not to care about cookies that match the regular expression that you provided.

Note: you may use Regexr to test your configuration.

Note: as Memento runs over HTTP, secure cookies will be downgraded to normal cookies.

Recipe: ignore Google Analytics cookies

A common use case is ignoring Google Analytics cookies : _ga, _gid, _gat, _gac-*, AMP_TOKEN. The following configuration tells Memento to ignore such cookies:

{
  // ... your configuration
  "ignoreCookiesPattern": "AMP_TOKEN|_ga.*|_gid"
}

Examples

Using the CLI

Launching Memento will start the interactive Memento CLI, where you can type commands to modify the cached requests and responses. The documentation can be found by typing help in the command prompt.

Command: import

You may import cURL commands into Memento. This feature is intended to be used as such:

  1. develop your app like the API is ready

  2. open the "network" tab in the Chrome devtools

  3. right click the failed request and select "copy as cURL"

    How to copy curl

  4. use the "import" command in memento and paste the cURL command.

    How to import curl

  5. you can now edit the response in your editor to stub the API call 🎉

Note: Memento will open the editor defined in your EDITOR environment variable. Non-terminal editors are not supported.

Cache location

By default, memento will create a .memento-cache directory in the current directory where each response will be mapped to a directory containing:

  • metadata.json - A file containing information about the request and the response.
  • body.{json,xml,txt} - The response content. The extension depends on the response content-type header. You may edit this file to edit the response.

You may override this directory by providing a cacheDirectory in the configuration file. this may be useful for storing environment dependent responses.

Contributing

Below is a list of commands you will probably find useful.

# Start TS compilation in watch mode
yarn start

# Start the local server
yarn dev
You can’t perform that action at this time.