Maintainer: Naramsim

A PokeAPI wrapper intended for browsers. Comes fully asynchronous, zero dependencies and built-in cache. Offers also Image Caching through the inclusion of a Service Worker. For a Node (server-side) wrapper see: pokedex-promise-v2

• Install
• Usage
  • Example requests
• Configuration
  • Caching images
• Tests
• Endpoints
  • Root Endpoints list
  • Custom URLs and paths

// As a Node module
// npm install pokeapi-js-wrapper --save
const pokedex = await Pokedex.init();
console.log(await pokedex.getPokemonsList())

<!-- Included in some HTML -->
<script type="module">
    import {Pokedex} from "https://cdn.jsdelivr.net/gh/pokeapi/pokeapi-js-wrapper@beta/src/index.js"
    const pokedex = await Pokedex.init();
    const version = await pokedex.getVersionByName(1)
    console.log(version)
</script>

// with await, be sure to be in an async function (and in a try/catch)
(async () => {
  const golduck = await pokedex.getPokemonByName("golduck")
  console.log(golduck)
})()

// or with Promises
pokedex.getPokemonByName("eevee")
  .then(function(response) {
    console.log(response)
  })

pokedex.resource([
  "/api/v2/pokemon/36",
  "api/v2/berry/8",
  "https://pokeapi.co/api/v2/ability/9/",
]).then( response => {
  console.log(response)
})

Pass an Object to Pokedex.init() in order to configure it. Available options: protocol, hostName, versionPath, cache, timeout(ms), and cacheImages. Any option is optional 😄. All the default values can be found here

const customOptions = {
  protocol: "https",
  hostName: "localhost:443",
  versionPath: "/api/v2/",
  cache: true,
  timeout: 5 * 1000, // 5s
  cacheImages: true
}
const pokedex = await Pokedex.init(customOptions);

Pokeapi.co serves its Pokemon images through Github. For example, the front default DreamWorld image of Pikachu is found at this URL: https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/dream-world/25.svg.

pokeapi-js-wrapper enables browsers to cache all these images by:

1. enabling the config parameter cacheImages
2. serving our service worker from the root of your project

In this way when pokeapi-js-wrapper's Pokedex is initialized it will install and start the Service Worker you are serving at the root of your server. The Service Worker will intercept all the calls your HTML/CSS/JS are making to get PokeAPI's images and will cache them.

It's fundamental that you download the Service Worker we provide(Right Click + Save As) and you serve it from the root of your project/server. Service Workers in fact cannot be installed from a domain different than yours.

A basic example is hosted here.

pokeapi-js-wrapper can be tested using two strategies. One is with Node, since this package works with Node, and the other with a browser.

npm test

Or open /test/test.html in your browser. A live version can be found at gh-pages

All the endpoints and the functions to access PokeAPI's endpoints are listed in the long table below. Each function .ByName(name) accepts names and ids. The only 5 functions .ById(id) only accept ids. You can also pass an array to each function, it will retrieve the data for each element asynchronously.

response = await pokedex.getPokemonByName("eevee")

response = await pokedex.getPokemonSpeciesByName(25)

// `response` will be an Array containing 3 Objects
// response.forEach((item) => {console.log(item.size)}) // 80,50,20
response = await pokedex.getBerryByName(["cheri", "chesto", 5])

response = await pokedex.getMachineById(3)

For each PokeAPI's root endpoint we provide a method to get all the items served by that endpoint. By default the method will return every item in the endpoint. If needed an offset and a limit can be configured.

• offset is where to start. The first item that you will get. Default 0
• limit is how many items you want to list. Default 100000

TIP: Do not pass any config Object to your call, since you will get every item and everything will be cached

The following snippet will get the list of Pokémon between ID 34 and ID 44

const interval = {
  offset: 34,
  limit: 10,
}
pokedex.getPokemonsList(interval).then(function(response) {
  console.log(response)
})

Use .resource() to query any URL or path. Also this function accepts both single values and Arrays.

pokedex.resource([
  "/api/v2/pokemon/36",
  "api/v2/berry/8",
  "https://pokeapi.co/api/v2/ability/9/",
]).then(function(response) {
  console.log(response)
})

pokedex.resource("api/v2/berry/5").then(function(response) {
  console.log(response)
})