Nobody Publish Monsters

    This package has been deprecated

    Author message:

    Package no longer supported. Contact Support at for more info.


    0.56.2 • Public • Published

    superfly octokitty


    npm version isc license Build Status Conventional Commits FOSSA Status Gitter

    The Fly runtime is an open source Javascript environment built to run Edge Applications. It gives developers powerful caching, content modification, and routing tools.

    The runtime is based on v8, with a proxy-appropriate set of Javascript libraries. There are built in APIs for manipulating HTML and Image content, low level caching, and HTTP requests/responses. When possible, we use WhatWG standards (like fetch, Request, Response, Cache, ReadableStream).

    You can use it locally for development and testing, and deploy it to Fly's fleet of edge servers for production use.

    Edge Applications: the in between

    You can use Fly to build HTTP load balancers, caching services, etc, etc. Edge Applications are typically built to replace or augment infrastructure that runs between web apps and users.

    This in-between is a great place to solve certain categories of problems. If you need to solve one of these, you might want to build an Edge Application:

    • A/B testing at the load balancer layer
    • Route traffic to different cloud providers
    • Cache personalization data geographically close to individual users
    • Route authenticated users to specific apps
    • Enforce backend SLAs, serve fallback content when backends are degraded
    • Load balancers across cloud storage providers
    • Per user rate limiting (for APIs or apps)



    Homebrew is the quickest way to get started on macOS:

    brew tap superfly/brew && brew install superfly/brew/fly


    Use the standalone installer


    Use npm

    Other installation methods

    Standalone Install

    The standalone install is a tarball containing the Fly CLI, precompiled native extensions, and a nodejs binary. This is useful in containers or hosts with restricted access.

    To quickly install into /usr/local/lib/fly and /usr/local/bin/fly, run this script (requires sudo and not Windows compatible):

    curl | sh

    Otherwise, download one of the tarballs below and extract it yourself.



    The Fly CLI and runtime is built on Node.js with native extensions. As a result, installing from npm requires a proper C/C++ compiler toolchain and takes significantly longer than the other methods. If you're on Windows or don't have XCode/gcc installed, follow the node-gyp instructions before continuing.

    Install globally:

    npm install -g @fly/fly

    or as a devDependency in your project:

    npm install --save-dev @fly/fly


    Hello World!

    Write javascript code to a file (index.js):

    fly.http.respondWith((request) => {
      return new Response("Hello! We support whirled peas.", { status: 200})
    // if you'd prefer to be service worker compatible, this is also supported:
    // around addEventListener('fetch', function(event){})

    Start the fly server:

    fly server

    Visit your app:

    open http://localhost:3000

    Change code and configuration, it's reloaded seamlessly.

    How does it work?

    Simply put:

    • Uses a basic webpack configuration to bundle your javascript
    • Assumes the presence of index.js or index.ts
    • You can customize everything by creating a which will be loaded for you
    • Use npm packages compatible with the v8 javascript engine, you don't have access to node.js-specific concepts or packages.


    By default, fly will read your .fly.yml file in your current working directory.

    # .fly.yml
    app: my-app-name
      foo: bar
      - path/to/file


    • app - the app name, can be ommitted, useful for deployment purposes
    • config - arbitrary settings for your applications, accessible in your code via the global variable app.config
    • files - array of files, relative to your .fly.yml to include in the deployment. Can be accessed via fetch("file://path/to/file")


    You can require secrets in your app.config like this:

    # .fly.yml
    app: my-app-name
        fromSecret: secretKey

    In your code, you can seamlessly use this value like:


    When deployed on, secrets are fetched from an encrypted store. You need to pre-define your secrets via fly secrets:set <key> <value>.

    Locally, you need to define them in a .fly.secrets.yml file, make sure you add it to your .gitignore as it can contain sensitive data. Example file.

    # .fly.secrets.yml
    secretKey: <your secret value>


    By specifying a files property in your .fly.yml, it's possible to use fetch to load files without having to bundle them in your javascript directly.

    Locally, these are fetched from your filesystem. Deployed, these are fetched from our distributed store.

    Example usage in your code: (given a client/app.js file)

    // index.js
    addEventListener('fetch', function(event){
      event.respondWith(async function(){
        const res = await fetch("file://client/app.js")
        res.status // 200
        res.headers.set("content-type", "application/javascript")
        return res

    Note that fetching with the file: protocol returns a very basic response.

    Multiple environments

    Different environments (development, test, production) require different configurations. You can specify how each should behave by adding one level to your .fly.yml like:

    config: &config # your default config
      foo: bar
    default: &default
      app: your-app-name
        <<: *config
      <<: *default
      <<: *default
        <<: *config
        foo: not-bar
      <<: *default
        <<: *config
          fromSecret: fooSecret


    fly comes with mocha as its default testing framework.

    You can write unit tests and use fly test to run them within the fly environment:

    // ./test/index.spec.js
    import { MyModule } from '../my_module' // load some code
    import { expect } from 'chai'
    describe("MyModule", ()=>{
      it("works", function(){


    Once you're happy with your app, you can deploy to

    1. Login

    Use fly login to log into your account, if you don't have one, go create one!

    2. Create an app

    Make sure you've created your fly app for your account with fly apps:create [name] (name is optional)

    Set your app property in your .fly.yml

    3. Deploy!

    Using fly deploy, here's what happens:

    • Your code is bundled via webpack, it's also uglified to save space
    • Your code, source map and files are added to a simple tarball, gzipped and uploaded to the API using your token
    • We create a "release" for your app, those are immutable, changing anything (by using fly deploy or fly secrets:set) will trigger a new release which will be deployed automatically
    • Your code is distributed instantly(-ish) across our global fleet of servers


    Tail production logs with:

    fly logs


    Open source

    We develop fly in the open. We're Apache licensed and designed to run easily in local dev. You can deploy our core software to production, but it takes a little elbow grease and a fair amount of infrastructure. If you want to give this a try, let us know and we can help (and we would love related pull requests!).

    Our commercial offering is built on top of this library, with additional code for managing certificates, distributed caching, and multi-tenant isolation. Over time we expect to extract many of these features, document them, and include them in our open source releases.

    We support Let's Encrypt: We donate half our certificate management fees to Let's Encrypt every year.




    npm i @fly/fly


    DownloadsWeekly Downloads






    Unpacked Size

    37.8 kB

    Total Files


    Last publish


    • jeromegn
    • michaeldwan
    • mrkurt