{"id":14957583,"url":"https://github.com/buttercms/buttercms-js","last_synced_at":"2025-04-15T03:51:04.269Z","repository":{"id":8302818,"uuid":"55876587","full_name":"ButterCMS/buttercms-js","owner":"ButterCMS","description":"Node/JS API client for ButterCMS (https://buttercms.com)","archived":false,"fork":false,"pushed_at":"2025-04-03T07:05:30.000Z","size":1002,"stargazers_count":163,"open_issues_count":2,"forks_count":32,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-07T16:16:18.256Z","etag":null,"topics":["cms","express-js","hapi","koa","node","node-cms","nodejs","nodejs-cms"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ButterCMS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-10T02:16:47.000Z","updated_at":"2025-01-09T03:43:00.000Z","dependencies_parsed_at":"2024-01-26T22:27:40.833Z","dependency_job_id":"d91baf63-afdb-46de-abdf-3ebb9779412d","html_url":"https://github.com/ButterCMS/buttercms-js","commit_stats":{"total_commits":178,"total_committers":22,"mean_commits":8.090909090909092,"dds":0.8651685393258427,"last_synced_commit":"fd98185787e5e632798db017da6fee45b085a8ab"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ButterCMS%2Fbuttercms-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ButterCMS%2Fbuttercms-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ButterCMS%2Fbuttercms-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ButterCMS%2Fbuttercms-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ButterCMS","download_url":"https://codeload.github.com/ButterCMS/buttercms-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249003944,"owners_count":21196794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cms","express-js","hapi","koa","node","node-cms","nodejs","nodejs-cms"],"created_at":"2024-09-24T13:15:11.600Z","updated_at":"2025-04-15T03:51:04.260Z","avatar_url":"https://github.com/ButterCMS.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ButterCMS JS client\n\n[![npm version](https://img.shields.io/npm/v/buttercms.svg)](https://www.npmjs.org/package/buttercms)\n\n## Documentation\n\nFor a comprehensive list of examples, check out the [API documentation](https://buttercms.com/docs/api/).\n\nButterCMS-JS version 2 will be supported until May 2025, when Node v18 sunsets. \nButterCMS-JS version 3 is our current version and will be supported until May 2026 when Node v20 sunsets\nButterCMS-JS version 4 slated for launch in December 2025 when Node v22 is moved to maintenance mode.\n\n## Installation\n\nRequires Node.js version 20 or greater.\n\n```bash\nnpm install buttercms --save\n```\n\nButter can also be included directly in HTML:\n\n\u003c!-- {x-release-please-start-version} --\u003e\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/buttercms@3.0.1/dist/butter.min.js\"\u003e\u003c/script\u003e\n```\n\u003c!-- {x-release-please-end} --\u003e\n\n## Native Fetch\n\nButterCMS-JS version 2 will be using the native fetch API. This means that the fetch API will be used to make requests to the ButterCMS API. This is a breaking change for anyone using version 1 of the ButterCMS-JS package.\n\nNative fetch is built into Node v18 as well as all modern browsers. This lessens the need for third-party fetch libraries and achieves consistency between Node and browser environments.\n\n## Overview\n\nEvery resource is accessed via your butter instance:\n\nUsing ES6 or Typescript:\n\n```js\nimport Butter from \"buttercms\";\nconst butter = Butter(\"your_api_token\");\n```\n\nUsing CDN:\n\n```html\n\u003cscript\u003e\n  const butter = Butter(\"your_api_token\");\n\u003c/script\u003e\n```\n\nEvery resource method returns a promise:\n\n```js\n// Get blog posts\nbutter.post.list({page: 1, page_size: 10})\n  .then(function(response) {\n    console.log(response)\n  })\n  .catch(function(error) {\n    console.error(error)\n  })\n```\n\nIf using `async`/`await`:\n\n```js\nasync function getPosts() {\n  try {\n    const response = await butter.post.list({page: 1, page_size: 10});\n    console.log(response);\n  } catch (error) {\n    console.error(error);\n  }\n}\n```\n\n## Pages\n\nWhere you see params it is a plain js object, e.g. `{page: 1}`. For a list of params see the [API documentation](https://buttercms.com/docs/api/?javascript)\n\n* page\n  * `retrieve(page_type, page_slug[, params])`\n  * `list(page_type[, params])`\n  * `search(query[, params])`\n  * `cancelRequest()`\n  \n ```js\n// Get page\nbutter.page.retrieve(\"casestudy\", \"acme-co\").then(function(resp) {\n  console.log(resp)\n});\n```\n\nIf using `async`/`await`:\n\n```js\nasync function getPage() {\n  try {\n    const response = await butter.page.retrieve(\"casestudy\", \"acme-co\");\n    console.log(response);\n  } catch (error) {\n    console.error(error);\n  }\n}\n```\n\n## Collections\n\n* content\n  * `retrieve(collection[, params])`\n  * `cancelRequest()`\n\n```js\n// Get FAQ\nbutter.content.retrieve(\"faq\", {locale: \"es\"}).then(function(resp) {\n  console.log(resp)\n});\n```\nIf using `async`/`await`:\n\n```js\nasync function getFAQ() {\n  try {\n    const response = await butter.content.retrieve(\"faq\", {locale: \"es\"});\n    console.log(response);\n  } catch (error) {\n    console.error(error);\n  }\n}\n```\n\n\n### Preview mode\n\nPreview mode can be used to setup a staging website for previewing content fields or for testing content during local development. To fetch content from preview mode add an additional argument, `true`, to the package initialization:\n\n```js\nconst butter = Butter(\n  \"your butter API token\", \n  { testMode: true }\n);\n```\n\nOr use an environment variable:\n\n```js\nconst butter = Butter(\n  \"your butter API token\", \n  { testMode:  process.env.BUTTER_PREVIEW_MODE }\n);\n```\n\n## Blog Engine\n\n* post\n  * `retrieve(slug[, params])`\n  * `list([params])`\n  * `search(query[, params])`\n  * `cancelRequest()`\n* category\n  * `retrieve(slug[, params])`\n  * `list([params])`\n  * `cancelRequest()`\n* tag\n  * `retrieve(slug[, params])`\n  * `list([params])`\n  * `cancelRequest()`\n* author\n  * `retrieve(slug[, params])`\n  * `list([params])`\n  * `cancelRequest()`\n* feed\n  * `retrieve(type[, params])`\n  * `cancelRequest()`\n  \nSee our [node app](https://github.com/buttercms/nodejs-cms-express-blog) for a full example.\n\n## Timeouts\n\nThe default timeout threshold is 3000ms but you can change it:\n\n```js\nconst butter = Butter(\n  \"your butter API token\", \n  { timeout: 5000 }\n);\n```\n\n## Caching\n\nThe default cache is set to `default`:\n\n```js\nconst butter = Butter(\n  \"your butter API token\", \n  { cache: \"only-if-cached\" }\n);\n```\n\n## Canceling a request\n\nEach resource returns a `cancelRequest` method that can be used to cancel a request:\n\n```js\nbutter.post.cancelRequest();\n```\n\nThis will cancel all pending requests for that resource type. It will catch the cancelation and return a rejected Promise for your `.catch()` method or be able to be caught in an `async` function via a `try`/`catch` block.\n\n\n## Hooks\n\nIf you need to custom headers, caching, automatic retry or any other specific functionality on the transport layer, you can hook up into our fetch hooks. The following hooks are available as Butter configuration options:\n\n```js\nconst butter = Butter(\n  \"your butter API token\", \n  { \n    onError: Function,\n    onRequest: Function,\n    onResponse: Function\n  }\n);\n```\n\n**onRequest** - called prior to making a request to the API. This can be declared as an async function to allow for async operations to be performed before the request is made.\n\n`onRequest(resource, config)`\n\n`resource` - The resource is the Butter API endpoint to be called\n`config` - This is the configuration object that will be used to make the request\n\n`config` includes:\n\n`cancelRequest` - A function that can be called to cancel the request in the hook\n`headers` - The headers that will be sent with the request. This is in the JS `Headers` API format. Users are able to modify these headers in the hook.\n`options` - Options are the original config options set when initializing the Butter instance. This includes the `cache`, `testMode`, `timeout`. Hook functions are not included in this object.\n`params` - The query parameters that will be sent with the request. Users are able to modify these parameters in the hook.\n`type` - The type of resource api that is being requested. This string helps the developer to differentiate what resource is being called in the global hook.\n\n`options`, `headers`, and `params`  are to be returned by the onRequest hook for further processing and request.\n\n**onResponse** - called after a response is received from the API. This can be declared as an async function to allow for async operations to be performed after the response is received.\n\n`onResponse (response, config)`\n\n`response` - The response object that was received from the API. This is in the JS `Fetch Response` API format and is a clone of the original response object. This will allow the user to parse the response to get the data they need whether it be JSON, text, blob, etc. The original response will be returned as JSON to the resource function call's promise resolution.\n\n`config` - This is the configuration object that was used to make the request\n\n`config` includes:\n\n`options` - Options are the original config options set when initializing the Butter instance. This includes the `cache`, `testMode`, `timeout`. Hook functions are not included in this object.\n`params` - The query parameters were sent with the request. \n`type` - The type of resource api that was requested. This string helps the developer to differentiate what resource was called in the global hook.\n\n`onResponse` expects no return values.\n\n**onError** - called when an error is received from the API. This is not considered an async function.\n\n`onError (errors, config)`\n\n`errors` - the errors returned from the API and/or the fetch request. Comes in the following object format:\n\n```\n{\n    details: \"Error details\",\n}\n```\n\n`config` includes:\n\n`options` - Options are the original config options set when initializing the Butter instance. This includes the `cache`, `testMode`, `timeout`. Hook functions are not included in this object.\n`params` - The query parameters were sent with the request. \n`type` - The type of resource api that was requested. This string helps the developer to differentiate what resource was called in the global hook.\n\n`onError` expects no return values.\n\n## Documentation\n\nDocumentation is available at https://buttercms.com/docs/api/node\n\n### Other\n\nView NodeJS [Blog engine](https://buttercms.com/nodejs-blog-engine/) and [Full CMS](https://buttercms.com/nodejs-cms/) for other examples of using ButterCMS with NodeJS.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercms%2Fbuttercms-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuttercms%2Fbuttercms-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercms%2Fbuttercms-js/lists"}