Major Rewrite and v2 Release

[NickMcBurney]

This is a proposal for a complete rewrite of the existing buttercms JavaScript client and I welcome feedback from the ButterCMS team and community.

Why am I proposing a new major version?

I believe with modern tooling I can improve developer experience, increase reliability, reduce workload for ButterCMS team and reduce package size.

Why is this important?

Tooling could (and should) be a consideration for teams looking into ButterCMS and in order to support growing user base and keeping existing (dev) users happy the ButterCMS client package needs to be reliable, fast (both in node + client side) and provide a good developer experience. I want to help Butter by providing modern tooling for a modern CMS ❤

My Proposal

I have rewritten the package using modern tooling:

• ⚡ Replace axios with isomorphic-unfetch to support both Node and Client side API calls - potential ⚠ breaking change - see "Potential Risks/Breaking Changes" below
• ⚡👩‍💻 Rollup Builds (ES/CJS) - Reduced package size using modern JS APIs
• 👩‍💻🧈👤 100% Typescript (improved codebase reliability, improved DX) - Thanks to @jackdomleo7 https://github.com/ButterCMS/buttercms-js/pull/42
• ✨ Implement Automatic Retries (configurable) - if the fetch call fails we can retry and user can set number of times to retry (default it 1) - so if a request fails it will try 1 more time
• 👩‍💻🧈 Jest unit tests - reducing risk of future updates causing regression in the package
• 👩‍💻🧈 Rome.tools Linter/formatter to enforce coding standards and best practices
• 👩‍💻🧈 Implement auto shipit to automatically generate new release versions (in Github + npm) as well as auto-generate CHANGELOG.md file based on PR commits + labels. Fixes #49 Fixes #51
• 👩‍💻🧈 [TBC] Implemented pnpm as package manager (faster dependency installs, see: https://pnpm.io/benchmarks) - to be confirmed - see 'Progress' near bottom

Benefits legend

👩‍💻 Developer Experience 👤 (dev-user) Experience 🧈 (dev-contributors) Experience ⚡ (client/browser) Performance ✨ New Feature

Potential Risks/Breaking Changes

• Current version supports Node v4+ > this rebuilt version would support Node 14+ --- Risk/Mitigation: I see version support change as low risk due to Node 4 reaching end-of-life status in April 2018 - this package is intended for teams using modern node systems with support for v14+ - see Node Release Schedule for additional information.
• Removal of axios - with axios there is idea of interceptors which can be used for amending requests before calling --- Risk/Mitigation: I have included hooks for before and after API calls which can be used to perform specific actions - but may not cover all use-cases - as I don't use these interceptors in my usage im not familiar with what/where/why they might be used - need some feedback on this.
• ⚠ Response will no longer be wrapped in a data: {} so where as previously to access butter content response.data.data was required you will now just need response.data --- Risk/Mitigation: This is a breaking change, although is benefitial as it will greatly reduce/tidy code for developers using the package - running

Why remove axios?

Axios is a package which covers a wide range of usage for both node/browser enviroments and due to the extensive functionality provided (most of which not used by buttercms) its a relatively large dependency: ~11kb - making up over half of current package size. By replacing with a modern alternative which also works in both node+browser I can significantly reduce package size.

Compatibility

Node.js: v14.17.0+ Chrome: 66+ Edge: 16+ Safari: 12.1+ Safari on iOS: 12.2+ Firefox: 57+ Samsung Browser: 9.2+

Unit Tests

Progress

• [x] Core work to replace/replicate existing package functionality and end-user syntax e.g. butter.posts.search(…)
• [x] ✨New Feature: Automatic Retry
• [x] Improve error handling
• [x] Implement unit tests
• [ ] Confirm preferred package manager with 🧈 team - recommended pnpm
• [x] Internal use-case testing - where I work we have use a wrapper utility for the buttercms package with some 40+ unit tests - I want to try testing new package version here as our tests will provide good level of coverage on top of built-in unit tests
• [ ] Update Readme.md
• [ ] Setup autos shipit (🧈 team required for this)

Next Steps:

1. (🧈 team/community) review / feedback
2. (🧈 team) Implement auto shipit environment variables into GitHub (a variable will need adding for npm token - in order to automatically publish new versions)
3. Complete PR and merge to Butter organisation - with prerelease version and auto shipit --dryrun in place
4. Following successful dry run in autoship it, create new PR removing --dryrun from github action yaml

[ViolanteCodes]

@NickMcBurney

Thank you so much for this PR; it looks like some really excellent work. Unfortunately, our main developer in charge of major roadmap changes is currently taking a leave of absence, and given the size and complexity of these changes, we don't want to move forward on something like this without consulting them, as we want to make sure it fits in with the already scoped out roadmap changes, so it may be some time before we're able to sit down and figure out which pieces of these we're clear to implement and which we might have to do some collaboration on.

--Maria @ ButterCMS

[NickMcBurney]

@NickMcBurney

Thank you so much for this PR; it looks like some really excellent work. Unfortunately, our main developer in charge of major roadmap changes is currently taking a leave of absence, and given the size and complexity of these changes, we don't want to move forward on something like this without consulting them, as we want to make sure it fits in with the already scoped out roadmap changes, so it may be some time before we're able to sit down and figure out which pieces of these we're clear to implement and which we might have to do some collaboration on.

--Maria @ ButterCMS

Hey @ViolanteCodes,

Ok thanks for letting me know.

Would be great to catch-up once they're back.

I'll likely publish this privately/internally where I work so we can make use of benefits and will keep this PR updated with any updates.

Thanks Nick

[mipopon]

Can this PR be merged @ ButterCMS? The new v2.0.0 breaks because of missing types, it would be great if this can be merged.

[ViolanteCodes]

Can this PR be merged @ ButterCMS? The new v2.0.0 breaks because of missing types, it would be great if this can be merged.

@NickMcBurney @mipopon @jackdomleo7

We had a team meeting to discuss this PR on top of the V2 changes, and unfortunately, we don't think we can fit it in with the planned roadmap for the SDK at this time. Apologies for the inconvenience and the long wait, and thank you for your suggestions.