• Stars
    star
    3,439
  • Rank 12,993 (Top 0.3 %)
  • Language
    JavaScript
  • License
    Other
  • Created almost 9 years ago
  • Updated about 1 year ago

Reviews

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

Repository Details

A simple, declarative, and composable way to fetch data for React components

React Refetch

A simple, declarative, and composable way to fetch data for React components.

React Refetch Logo

Installation

build status npm version npm downloads

Requires React 0.14 or later.

npm install --save react-refetch

This assumes that youโ€™re using npm package manager with a module bundler like Webpack or Browserify to consume CommonJS modules.

The following ES6 functions are required:

Check the compatibility tables (Object.assign, Promise, fetch, Array.prototype.find) to make sure all browsers and platforms you need to support have these, and include polyfills as necessary.

Introduction

See Introducing React Refetch on the Heroku Engineering Blog for background and a quick introduction to this project.

Motivation

This project was inspired by (and forked from) React Redux. Redux/Flux is a wonderful library/pattern for applications that need to maintain complicated client-side state; however, if your application is mostly fetching and rendering read-only data from a server, it can over-complicate the architecture to fetch data in actions, reduce it into the store, only to select it back out again. The other approach of fetching data inside the component and dumping it in local state is also messy and makes components smarter and more mutable than they need to be. This module allows you to wrap a component in a connect() decorator like react-redux, but instead of mapping state to props, this lets you map props to URLs to props. This lets you keep your components completely stateless, describe data sources in a declarative manner, and delegate the complexities of data fetching to this module. Advanced options are also supported to lazy load data, poll for new data, and post data to the server.

Example

If you have a component called Profile that has a userId prop, you can wrap it in connect() to map userId to one or more requests and assign them to new props called userFetch and likesFetch:

import React, { Component } from 'react'
import { connect, PromiseState } from 'react-refetch'

class Profile extends Component {
  render() {
    // see below
  }
}

export default connect(props => ({
  userFetch: `/users/${props.userId}`,
  likesFetch: `/users/${props.userId}/likes`
}))(Profile)

When the component mounts, the requests will be calculated, fetched, and the result will be passed into the component as the props specified. The result is represented as a PromiseState, which is a synchronous representation of the fetch Promise. It will either be pending, fulfilled, or rejected. This makes it simple to reason about the fetch state at the point in time the component is rendered:

render() {
  const { userFetch, likesFetch } = this.props

  if (userFetch.pending) {
    return <LoadingAnimation/>
  } else if (userFetch.rejected) {
    return <Error error={userFetch.reason}/>
  } else if (userFetch.fulfilled) {
    return <User user={userFetch.value}/>
  }

  // similar for `likesFetch`
}

See the composing responses to see how to handle userFetch and likesFetch together. Although not included in this library because of application-specific defaults, see an example PromiseStateContainer and its example usage for a way to abstract and simplify the rendering of PromiseStates.

Refetching

When new props are received, the requests are re-calculated, and if they changed, the data is refetched and passed into the component as new PromiseStates. Using something like React Router to derive the props from the URL in the browser, the application can control state changes just by changing the URL. When the URL changes, the props change, which recalculates the requests, new data is fetched, and it is reinjected into the components:

react-refetch-flow

By default, the requests are compared using their URL, headers, and body; however, if you want to use a custom value for the comparison, set the comparison attribute on the request. This can be helpful when the request should or should not be refetched in response to a prop change that is not in the request itself. A common situation where this occurs is when two different requests should be refetched together even though one of the requests does not actually include the prop. Note, this is using the request object syntax for userStatsFetch instead of just a plain URL string. This syntax allows for more advanced options. See the API documentation for details:

connect(props => ({
  usersFetch:  `/users?status=${props.status}&page=${props.page}`,
  userStatsFetch: { url: `/users/stats`, comparison: `${props.status}:${props.page}` }
}))(UsersList)

In this example, usersFetch is refetched every time props.status or props.page changes because the URL is changed. However, userStatsFetch does not contain these props in its URL, so would not normally be refetched, but because we added comparison: ${props.status}:${props.page}, it will be refetched along with usersFetch. In general, you should only rely on changes to the requests themselves to control when data is refetched, but this technique can be helpful when finer-grained control is needed.

If you always want data to be refetched when any new props are received, set the force: true option on the request. This will take precedence over any custom comparison and the default request comparison. For example:

connect(props => ({
  usersFetch: `/users?status=${props.status}&page=${props.page}`,
  userStatsFetch: { url: `/users/stats`, force: true }
}))(UsersList)

Setting force: true should be avoided if at all possible because it could result in extraneous data fetching and rendering of the component. Try to use the default comparison or custom comparison option instead.

Automatic Refreshing

If the refreshInterval option is provided along with a URL, the data will be refreshed that many milliseconds after the last successful response. If a request was ever rejected, it will not be refreshed or otherwise retried. In this example, likesFetch will be refreshed every minute. Note, this is using the request object syntax for likeFetch instead of just a plain URL string. This syntax allows for more advanced options. See the API documentation for details.

connect(props => ({
  userFetch:`/users/${props.userId}`,
  likesFetch: { url: `/users/${props.userId}/likes`, refreshInterval: 60000 }
}))(Profile)

When refreshing, the PromiseState will be the same as the previous fulfilled state, but with the refreshing attribute set. That is, pending will remain unset and the existing value will be left intact. When the refresh completes, refreshing will be unset and the value will be updated with the latest data. If the refresh is rejected, the PromiseState will move into a rejected and not attempt to refresh again.

Fetch Functions

Instead of mapping the props directly to a URL string or request object, you can also map the props to a function that returns a URL string or request object. When the component receives props, instead of the data being fetched immediately and injected as a PromiseState, the function is bound to the props and injected into the component as functional prop to be called later (usually in response to a user action). This can be used to either lazy load data, post data to the server, or refresh data. These are best shown with examples:

Lazy Loading

Here is a simple example of lazy loading the likesFetch with a function:

connect(props => ({
  userFetch: `/users/${props.userId}`,
  lazyFetchLikes: max => ({
    likesFetch: `/users/${props.userId}/likes?max=${max}`
  })
}))(Profile)

In this example, userFetch is fetched normally when the component receives props, but lazyFetchLikes is a function that returns likesFetch, so nothing is fetched immediately. Instead lazyFetchLikes is injected into the component as a function to be called later inside the component:

this.props.lazyFetchLikes(10)

When this function is called, the request is calculated using both the bound props and any passed in arguments, and the likesFetch result is injected into the component normally as a PromiseState.

Posting Data

Functions can also be used for post data to the server in response to a user action. For example:

connect(props => ({
  postLike: subject => ({
    postLikeResponse: {
      url: `/users/${props.userId}/likes`,
      method: 'POST',
      body: JSON.stringify({ subject })
    }
  })
}))(Profile)

The postLike function is injected in as a prop, which can then be tied to a button:

<button onClick={() => this.props.postLike(someSubject)}>Like!</button>

When the user clicks the button, someSubject is posted to the URL and the response is injected as a new postLikeResponse prop as a PromiseState to show progress and feedback to the user.

Manually Refreshing Data

Functions can also be used to manually refresh data by overwriting an existing PromiseState:

connect(props => {
 const url = `/users/${props.userId}`

 return {
   userFetch: url,
   refreshUser: () => ({
     userFetch: {
       url,
       force: true,
       refreshing: true
     }
   })
 }
})(Profile)

The userFetch data is first loaded normally when the component receives props, but the refreshUser function is also injected into the component. When this.props.refreshUser() is called, the request is calculated, and compared with the existing userFetch request. If the request changed (or force: true), the data is refetched and the existing userFetch PromiseState is overwritten. This should generally only be used for user-invoked refreshes; see above for automatically refreshing on an interval.

Note, the example above sets force: true and refreshing: true on the request returned by the refreshUser() function. These attributes are optional, but commonly used with manual refreshes. force: true avoids the default request comparison (e.g. url, method, headers, body) with the existing userFetch request so that every time this.props.refreshUser() is called, a fetch is performed. Because the request would not have changed from the last prop change in the example above, force: true is required in this case for the fetch to occur when this.props.refreshUser() is called. refreshing: true avoids the existing PromiseState from being cleared while fetch is in progress.

Posting + Refreshing Data

The two examples above can be combined to post data to the server and refresh an existing PromiseState. This is a common pattern when responding to a user action to update a resource and reflect that update in the component. For example, if PATCH /users/:user_id responds with the updated user, it can be used to overwrite the existing userFetch when the user updates her name:

connect(props => ({
  userFetch: `/users/${props.userId}`,
  updateUser: (firstName, lastName) => ({
    userFetch: {
      url: `/users/${props.userId}`
      method: 'PATCH'
      body: JSON.stringify({ firstName, lastName })
     }
   })
}))(Profile)

Composing Responses

If a component needs data from more than one URL, the PromiseStates can be combined with PromiseState.all() to be pending until all the PromiseStates have been fulfilled. For example:

render() {
  const { userFetch, likesFetch } = this.props

  // compose multiple PromiseStates together to wait on them as a whole
  const allFetches = PromiseState.all([userFetch, likesFetch])

  // render the different promise states
  if (allFetches.pending) {
    return <LoadingAnimation/>
  } else if (allFetches.rejected) {
    return <Error error={allFetches.reason}/>
  } else if (allFetches.fulfilled) {
    // decompose the PromiseState back into individual
    const [user, likes] = allFetches.value
    return (
      <div>
          <User data={user}/>
          <Likes data={likes}/>
      </div>
    )
  }
}

Similarly, PromiseState.race() can be used to return the first settled PromiseState. Like their asynchronous Promise counterparts, PromiseStates can be chained with then() and catch(); however, the handlers are run immediately to transform the existing state. This can be helpful to handle errors or transform values as part of a composition. For example, to provide a fallback value to likesFetch in the case of failure:

PromiseState.all([userFetch, likesFetch.catch(reason => [])])

Chaining Requests

Inside of connect(), requests can be chained using then(), catch(), andThen() and andCatch() to trigger additional requests after a previous request is fulfilled. These are not to be confused with the similar sounding functions on PromiseState, which are on the response side, are synchronous, and are executed for every change of the PromiseState.

then() is helpful for cases where multiple requests are required to get the data needed by the component and the subsequent request relies on data from the previous request. For example, if you need to make a request to /foos/${name} to look up foo.id and then make a second request to /bar-for-foos-by-id/${foo.id} and return the whole thing as barFetch (the component will not have access to the intermediate foo):

connect(({ name }) => ({
  barFetch: {
    url: `/foos/${name}`,
    then: foo => `/bar-for-foos-by-id/${foo.id}`
  }
}))

andThen() is similar, but is intended for side effect requests where you still need access to the result of the first request and/or need to fanout to multiple requests:

connect(({ name }) => ({
  fooFetch: {
    url: `/foos/${name}`,
    andThen: foo => ({
      barFetch: `/bar-for-foos-by-id/${foo.id}`
    })
  }
}))

This is also helpful for cases where a fetch function is changing data that is in some other fetch that is a collection. For example, if you have a list of foos and you create a new foo and the list needs to be refreshed:

 connect(({ name }) => ({
    foosFetch: '/foos',
    createFoo: name => ({
      fooCreation: {
        method: 'POST',
        url: '/foos',
        andThen: () => ({
          foosFetch: {
            url: '/foos',
            refreshing: true
          }
        })
      }
    })
  }))

catch and andCatch are similar, but for error cases.

Identity Requests: Static Data & Transforming Responses

To support static data and response transformations, there is a special kind of request called an "identity request" that has a value instead of a url. The value is passed through directly to the PromiseState without actually fetching anything. In its pure form, it looks like this:

connect(props => ({
  usersFetch: {
    value: [
      {
        id: 1,
        name: 'Jane Doe',
        verified: true
      },
      {
        id: 2,
        name: 'John Doe',
        verified: false
      }
    ]
  }
}))(Users)

In this case, the usersFetch PromiseState will be set to the provided list of users. The use case for identity requests by themselves is limited to mostly injecting static data during development and testing; however, they can be quite powerful when used with request chaining. For example, it is possible to fetch data from the server, filter it within a then function, and return an identity request:

connect(props => ({
  usersFetch: {
    url: `/users`,
    then: (users) => ({
      value: users.filter(u => u.verified)
    })
  }
}))(Users)

Note, this form of transformation is similar to what is possible on the PromiseState (i.e. this.props.usersFetch.then(users => users.filter(u => u.verified))); however, this has the advantage of only being called when usersFetch changes and keeps the logic out of the component.

Identity requests can also be provided a Promise (or any "thenable") or a Function. If value is a Promise, the PromiseState will be pending until the Promise is resolved. This can be helpful for asynchronous, non-fetch operations (e.g. file i/o) that want to use a similar pattern as fetch operations. If value is a Function, it will be evaluated with no arguments and its return value will be used instead, as in cases described above. The Function will only be called when comparison changes. This can be helpful for cases where you want to provide an identify request, but it is expensive to evaluate. By wrapping it in a function, it is only evaluated when something changes.

connect(props => ({
  userFetch: {
    comparison: props.userId,
    value: () => SomeExternalAPI.getUser(`/users/${props.userId}`)
  }
}))(Users)

Accessing Headers & Metadata

Both request and response headers and other metadata are accessible. Custom request headers can be set on the request as an object:

connect(props => ({
  userFetch: {
    url: `/users/${props.userId}`,
    headers: {
      FOO: 'foo',
      BAR: 'bar'
    }
  }
}))(Profile)

The raw Request and Response can be accessed via the meta attribute on the PromiseState. For example, to access the a response header:

userFetch.meta.response.headers.get('FOO')

Do not attempt to read bodies directly from meta.request or meta.response. They are provided for metadata purposes only.

Setting defaults and hooking into internal processing

It is possible to modify the various defaults used by React Refetch, as well as substitute in custom implementations of internal functions. A simple use case would be to avoid repeating the same option for every fetch block:

import { connect } from 'react-refetch'
const refetch = connect.defaults({
  credentials: 'include'
})

refetch(props => ({
  userFetch: `/users/${props.userId}`
}))(Profile)

A more advanced use case would be to replace the buildRequest internal function to, for example, modify headers on the fly based on the URL of the request, or using advanced Request options:

// api-connector.js
import { connect } from 'react-refetch'
import urlJoin from 'url-join'
import { getPrivateToken } from './api-tokens'

const baseUrl = 'https://api.example.com/'

export default connect.defaults({
  buildRequest: function (mapping) {
    const options = {
      method: mapping.method,
      cache: 'force-cache',
      referrer: 'https://example.com',
      headers: mapping.headers,
      credentials: mapping.credentials,
      redirect: mapping.redirect,
      mode: mapping.mode,
      body: mapping.body
    }

    if (mapping.url.match(/private/)) {
      options.headers['X-Api-Token'] = getPrivateToken()
    }

    if (mapping.url.match(/listOfServers.json$/)) {
      options.integrity = 'sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE='
    }

    return new Request(urlJoin(baseUrl, mapping.url), options)
  }
})

// ProfileComponent.js
import connect from './api-connector'
connect(props => ({
  userFetch: `/users/${props.userId}`,
  serversFetch: `/listOfServers.json`
}))(Profile)

You can also replace the handleResponse function, which takes a Response, and should return a Promise that resolves to the value of the response, or rejects based on the body, headers, status code, etc. You can use it, for example, to parse CSV instead of JSON:

// api-connector.js
import { connect } from 'react-refetch'
import { parse } from 'csv'

const csvConnector = connect.defaults({
  handleResponse: function (response) {
    if (response.headers.get('content-length') === '0' || response.status === 204) {
      return
    }

    const csv = response.text()

    if (response.status >= 200 && response.status < 300) {
      return csv.then(text => new Promise((resolve, reject) => {
        parse(text, (err, data) => {
          if (err) { reject(err) }
          resolve(data)
        })
      }))
    } else {
      return csv.then(cause => Promise.reject(new Error(cause)))
    }
  }
})

csvConnector(props => ({
  userFetch: `/users/${props.userId}.csv`
}))(Profile)

On changing the fetch and Request implementations

Through this same API it is possible to change the internal fetch and Request implementations. This could be useful for a number of reasons, such as precise control over requests or customisation that is not possible with either buildRequest or handleResponse.

For example, here's a simplistic implementation of a "caching fetch," which will cache the result of successful requests for a minute, regardless of headers:

import { connect } from 'react-refetch'

const cache = new Map()
function cachingFetch(input, init) {
  const req = new Request(input, init)
  const now = new Date().getTime()
  const oneMinuteAgo = now - 60000
  const cached = cache.get(req.url)

  if (cached && cached.time < oneMinuteAgo) {
    return new Promise(resolve => resolve(cached.response.clone()))
  }

  return fetch(req).then(response => {
    cache.set(req.url, {
      time: now,
      response: response.clone()
    })

    return response
  })
}

connect.defaults({ fetch: cachingFetch })(props => ({
  userFetch: `/users/${props.userId}`
}))(Profile)

When using this feature, make sure to read the fetch API and interface documentation and all related topics. Notably, you need to keep in mind that the body of a Response can only be consumed once, so if you need to read it in your custom fetch, you also need to recreate a brand new Response (or a .clone() of the original one if you're not modifying the body) so React Refetch can work properly.

This is an advanced feature. Use existing declarative functionality wherever possible. Customise buildRequest or handleResponse if these can work instead. Please be aware that changing the fetch (or Request) implementation could conflict with built-in current or future functionality.

Unit Testing Connected Components

For unit testing components connected, a non-default export of the unconnected component can be exposed to allow unit tests to inject their own PromiseState(s) as props. This allows for unit tests to test both success and error scenarios without having to deal with mocking HTTP, timing of responses, or other details about how the PromiseState(s) is fulfilled -- instead, they can just focus on asserting that the component itself renders the PromiseState(s) correctly in various scenarios.

The recommended naming convention for the unconnected component is to prepend an underscore to the component name. For example, if there is a component called Profile, add a non-default export of _Profile before the default export with connect:

class Profile extends React.Component {
  static propTypes = {
    userFetch: PropTypes.instanceOf(PromiseState).isRequired,
  }

  render() {
    const { userFetch } = this.props

    if (userFetch.pending) {
      return <LoadingAnimation/>
    } else if (userFetch.rejected) {
      return <ErrorBox error={userFetch.reason}/>
    } else if (userFetch.fulfilled) {
      return <User user={userFetch.value}/>
    }
  }
}

export { Profile as _Profile }

export default connect(props => ({
  userFetch: `/users/${props.userId}`
}))(Profile)

Now, unit tests can use the static methods on PromiseState to inject their own PromiseState(s) as props. For example, here is a unit test using Enzyme to shallow render the unconnected _Profile and provides a pending PromiseState and asserts that the LoadingAnimation is present:

const c = shallow(
  <_Profile
    userFetch={PromiseState.create()}
  />
)

expect(wrapper.find(LoadingAnimation)).to.have.length(1)

Similarly, the rejected and fulfilled cases can be tested:

const expectedError = new Error('boom')

const c = shallow(
  <_Profile
    userFetch={PromiseState.reject(expectedError)}
  />
)

expect(c.find(ErrorBox).first().prop().error).toEqual(expectedError)
const user = new User()

const c = shallow(
  <_Profile
    userFetch={PromiseState.resolve(user)}
  />
)

expect(wrapper.find(User)).to.have.length(1)

Complete Example

This is a complex example demonstrating various feature at once:

import React, { Component, PropTypes } from 'react'
import { connect, PromiseState } from 'react-refetch'

class Profile extends React.Component {
  static propTypes = {
    params: PropTypes.shape({
      userId: PropTypes.string.isRequired,
    }).isRequired,
    userFetch: PropTypes.instanceOf(PromiseState).isRequired
    likesFetch: PropTypes.instanceOf(PromiseState).isRequired
    updateStatus: PropTypes.func.isRequired
    updateStatusResponse: PropTypes.instanceOf(PromiseState) // will not be set until after `updateStatus()` is called
  }

  render() {
    const { userFetch, likesFetch } = this.props

    // compose multiple PromiseStates together to wait on them as a whole
    const allFetches = PromiseState.all([userFetch, likesFetch])

    // render the different promise states
    if (allFetches.pending) {
      return <LoadingAnimation/>
    } else if (allFetches.rejected) {
      return <Error error={allFetches.reason}/>
    } else if (allFetches.fulfilled) {
      // decompose the PromiseState back into individual
      const [user, likes] = allFetches.value
      return (
        <div>
          <User data={user}/>
          <Likes data={likes}/>
        </div>
      )
    }

    // call `updateStatus()` on button click
    <button onClick={() => { this.props.updateStatus("Hello World")} }>Update Status</button>

    if (updateStatusResponse) {
      // render the different promise states, but will be `null` until `updateStatus()` is called
    }
  }
}

// declare the requests for fetching the data, assign them props, and connect to the component.
export default connect(props => {
  return {
    // simple GET from a URL injected as `userFetch` prop
    // if `userId` changes, data will be refetched
    userFetch: `/users/${props.params.userId}`,

    // similar to `userFetch`, but using object syntax
    // specifies a refresh interval to poll for new data
    likesFetch: {
      url: `/users/${props.userId}/likes`,
      refreshInterval: 60000
    },

    // declaring a request as a function
    // not immediately fetched, but rather bound to the `userId` prop and injected as `updateStatus` prop
    // when `updateStatus` is called, the `status` is posted and the response is injected as `updateStatusResponse` prop.
    updateStatus: status => ({
      updateStatusResponse: {
        url: `/users/${props.params.userId}/status`,
        method: 'POST',
        body: status
      }
    })
  }
})(Profile)

TypeScript

If you are using React Refetch in a project that is using TypeScript, this library ships with type definitions.

Below is an example connected component in TypeScript. Note how there is both an OuterProps and InnerProps. The OuterProp are the props the component receives from the outside. In this example, the OuterProps would just be userId: string the caller is expected to pass in (e.g. <UserWidget userId="user-123"/>). The InnerProps are the PromiseState props that the connect() function injects into the component when fetching data. Since the InnerProps include the OuterProps, they are defined as InnerProps extends OuterProps and then the component itself extends React.Component<InnerProps>. This allows the component to have access to both the userId: string and userFetch: PromiseState<User> internally. However, the connect function returns a component with only the OuterProps (e.g. React.Component<OuterProps>) so callers only need to pass in userId: string.

interface OuterProps {
    userId: string
}

interface InnerProps extends OuterProps {
    userFetch: PromiseState<User>
}

class UserWidget extends React.Component<InnerProps> {
  render() {
    return (
      <ul>
        <li>{ this.props.userId }</li>
        <li>{ this.props.userFetch.fulfilled && this.props.userFetch.value.name }</li>
      </ul>
    )
  }
}

export default connect<OuterProps, InnerProps>((props) => ({
  userFetch: `/users/${props.userId}`
}))(UserWidget)

API Documentation

Support

This software is provided "as is", without warranty or support of any kind, express or implied. See license for details.

License

MIT

More Repositories

1

legacy-cli

Heroku CLI
Ruby
1,370
star
2

heroku-pg-extras

A heroku plugin for awesome pg:* commands that are also great and fun and super.
JavaScript
1,306
star
3

heroku-buildpack-nodejs

The official Heroku buildpack for Node.js apps.
Shell
1,265
star
4

node-js-getting-started

Getting Started with Node on Heroku
EJS
1,054
star
5

logplex

[DEPRECATED] Heroku log router
Erlang
984
star
6

heroku-buildpack-python

The official Heroku buildpack for Python apps
Ruby
953
star
7

heroku-django-template

A Django 2.0 base template featuring all recommended best practices for deployment on Heroku and local development.
Python
901
star
8

node-js-sample

This repository is deprecated. Head over to https://github.com/heroku/node-js-getting-started
JavaScript
847
star
9

cli

Heroku CLI
JavaScript
847
star
10

rails_12factor

Ruby
845
star
11

python-getting-started

Getting Started with Python on Heroku.
Python
818
star
12

heroku-buildpack-php

The official PHP buildpack for Heroku.
Shell
799
star
13

heroku-buildpack-go

Heroku Go Buildpack
Shell
790
star
14

heroku-buildpack-ruby

Heroku's Ruby Buildpack
Ruby
778
star
15

hk

DEPRECATED: see
Go
709
star
16

heroku-buildpack-static

[DEPRECATED] Heroku buildpack for handling static sites and single page web apps
Ruby
681
star
17

heroku-repo

Plugin for heroku CLI that can manipulate the repo
JavaScript
680
star
18

vegur

Vegur: HTTP Proxy Library
Erlang
620
star
19

heroku-accounts

Helps use multiple accounts on Heroku.
JavaScript
548
star
20

django-heroku

[DEPRECATED] Do not use! See https://github.com/heroku/django-heroku/issues/56
Python
465
star
21

heroku-buildpack-pgbouncer

Run pgbouncer in a dyno along with your application
Shell
335
star
22

devcenter-embedded-tomcat

Java
330
star
23

webapp-runner

Lightweight Application Launcher. Launch your webapp in the most popular open source web container available with a single command.
Java
319
star
24

docker-registry-client

A Go API client for the v2 Docker Registry API
Go
287
star
25

heroku-buildpack-google-chrome

Run (headless) Google Chrome on Heroku
Shell
283
star
26

stack-images

Recipies for building Heroku's stack images
Shell
264
star
27

java-getting-started

Getting Started with Java on Heroku
HTML
248
star
28

identity

[DEPRECATED] Login and OAuth management service for Heroku
CSS
247
star
29

go-getting-started

Getting Started with Go on Heroku https://devcenter.heroku.com/articles/getting-started-with-go
Dockerfile
246
star
30

heroku-buildpack-nginx

Run NGINX in a Heroku app
Shell
242
star
31

heroku-buildpack-apt

Buildpack that installs APT based dependencies
Shell
239
star
32

log-shuttle

HTTP log transport.
Go
236
star
33

terrier

Terrier is a Image and Container analysis tool that can be used to scan Images and Containers to identify and verify the presence of specific files according to their hashes.
Go
227
star
34

umpire

HTTP metrics monitoring endpoint
Ruby
221
star
35

platform-api

Ruby HTTP client for the Heroku API
Ruby
211
star
36

starboard

onboarding, offboarding, or crossboarding made easy
SCSS
204
star
37

salesforce-bulk

Python interface to the Salesforce.com Bulk API
Python
203
star
38

php-getting-started

Getting Started with PHP on Heroku
Twig
200
star
39

heroku-container-tools

DEPRECATED Heroku Toolbelt plugin to help configure, test and release apps to Heroku using local containers.
JavaScript
195
star
40

heroku-buildpack-scala

Heroku buildpack: Scala
Shell
190
star
41

node-heroku-client

A wrapper around the Heroku API for Node.js
JavaScript
188
star
42

vulcan

A build server in the cloud.
Ruby
172
star
43

pg_lock

Use Postgres advisory lock to isolate code execution across machines
Ruby
168
star
44

awsdetailedbilling

A toolkit for importing AWS detailed billing reports into Redshift
JavaScript
167
star
45

heroku-buildpack-java

A Heroku buildpack for Java apps.
Shell
167
star
46

pulse

DEPRECATED: Real-time Heroku operations dashboard
Clojure
161
star
47

heroku.rb

DEPRECATED! Official Heroku Ruby Legacy API wrapper
Ruby
161
star
48

heroku-buildpack-multi

[DEPRECATED] Please use https://devcenter.heroku.com/articles/using-multiple-buildpacks-for-an-app instead
Shell
157
star
49

erlang-in-anger

A little guide about how to be the Erlang medic in a time of war. It is first and foremost a collection of tips and tricks to help understand where failures come from, and a dictionary of different code snippets and practices that helped developers debug production systems that were built in Erlang.
TeX
157
star
50

plexy

A toolkit for building excellent APIs with Elixir
Elixir
154
star
51

heroku-buildpack-multi-procfile

Everyone gets a Procfile!
Shell
150
star
52

log2viz

DEFUNCT: Realtime analysis of your Heroku app logs.
Ruby
145
star
53

heroku.py

DEPRECATED! Heroku API wrapper for Python.
Python
142
star
54

facebook-template-nodejs

JavaScript
136
star
55

ruby-getting-started

Getting Started with Ruby on Heroku
Ruby
120
star
56

heroku-buildpack-chromedriver

Installs chromedriver in a Heroku slug
Shell
117
star
57

heroku-buildpack-clojure

Heroku's buildpack for Clojure applications.
Shell
115
star
58

mobile-template1

JavaScript
115
star
59

instruments

Collecting metrics over discrete time intervals
Go
112
star
60

heroku-sbt-plugin

An sbt plugin for deploying Heroku Scala applications
Scala
111
star
61

heroku-buildpack-erlang

Erlang buildpack
Shell
107
star
62

terraform-provider-heroku

Terraform Heroku provider
Go
99
star
63

cli-engine

TypeScript
97
star
64

semver.io

*DEPRECATED* The semver.io instance has now been sunset: https://github.com/heroku/semver.io/issues/74
CoffeeScript
96
star
65

facebook-template-php

example facebook app for heroku
PHP
96
star
66

dotnet-buildpack

ASP.NET 5 Buildpack
Shell
92
star
67

kensa

A tool to help Heroku add-on providers integrate their services with Heroku
Ruby
92
star
68

netrc

Reads and writes netrc files.
Ruby
89
star
69

hstore_example

Ruby
89
star
70

alpinehelloworld

An Alpine-based Docker example
Python
85
star
71

heroku-kong

๐Ÿ’ Kong API gateway as a Heroku app
Lua
84
star
72

heroku-buildpack-hello

Shell
82
star
73

heroku-releases-retry

CLI plugin to allow retrying the latest release-phase command
JavaScript
79
star
74

faceplate

A Node.js wrapper for Facebook authentication and API
JavaScript
76
star
75

rails_stdout_logging

Logs to stdout so you don't have to
Ruby
76
star
76

shaas

Shell as a Service: API to inspect and execute scripts in a server's environment via HTTP and WebSockets
Go
75
star
77

devcenter-spring-mvc-hibernate

AspectJ
75
star
78

heroku-buildpack-core-data

A Heroku Buildpack that generates a REST webservice from a Core Data model
Shell
74
star
79

heroku-buildpack-emberjs

**This buildpack is deprecated!** Please use the official Node.js buildpack combined with the static or nginx buildpack instead.
Ruby
72
star
80

facebook-template-python

Python
69
star
81

devcenter-java

Java
62
star
82

heroku-buildpack-c

C Language Pack
Shell
62
star
83

nibs

JavaScript
61
star
84

heroku-buildpack-gradle

This is a Heroku buildpack for Gradle apps. It uses Gradle to build your application and OpenJDK to run it.
Shell
61
star
85

heroku-buildpack-ember-cli

A Heroku buildpack for ember-cli apps; powers dashboard.heroku.com
Shell
60
star
86

heroku-guardian

Easy to use CLI security checks for the Heroku platform. Validate baseline security configurations for your own Heroku deployments.
Python
60
star
87

cnb-builder-images

Recipes for building Heroku's Cloud Native Buildpacks builder images
Java
59
star
88

list-of-ingredients

An example of using Create React App with Rails 5 API and ActiveAdmin on Heroku
Ruby
57
star
89

heroku-fork

Heroku CLI plugin to fork an existing app into a new app
JavaScript
55
star
90

salesforce-buildpack

Heroku Buildpack for Salesforce
Shell
53
star
91

ruby-rails-sample

Ruby
52
star
92

facebook-template-ruby

CSS
52
star
93

heroku-jupyterlab

An example of running JupyterLab on Heroku, with Amazon S3.
Python
52
star
94

heroku-maven-plugin

This plugin is used to deploy Java applications directly to Heroku without pushing to a Git repository.
Java
51
star
95

stillir

Cache environment variables as Erlang app variables
Erlang
51
star
96

rails_serve_static_assets

Ruby
49
star
97

heroku-gradle-plugin

A Gradle plugin for deploying JAR and WAR files to Heroku.
Java
49
star
98

x

A set of packages for reuse within Heroku Go applications
Go
49
star
99

template-java-spring-hibernate

Java
48
star
100

scala-getting-started

Getting Started with Scala / Play on Heroku
HTML
48
star