-
Notifications
You must be signed in to change notification settings - Fork 1
Home
The NextCapital Client allows partners to embed UIs and interact with NextCapital services from within their own applications.
See the Quick Start Guide for information on how to get the NextCapital Client up-and-running within your application.
NextCapital also provides an example Demo Application that makes use of the NextCapital Client. This can be a useful example of how to integrate the NextCapital client into your application.
When designing the client, we had several big goals:
- Minimize dependencies and potential conflicts with the parent application
- Allow NextCapital to make updates (bug fixes, new features, performance improvements, etc.) without partners having to make any changes
- Prevent the NextCapital Client from bloating the size of partner application bundles
- Prevent partners from being forced to sync their deployment schedule with the NextCapital deployment schedule
- Extreme ease of use for partners
In order to accomplish this, we decided on a split architecture:
- A tiny local client, installed via
npm
, that loads theremote
client - A remote client, served from NextCapital servers, that contains most of the NextCapital Client code
The local client is very small. It contains just:
- The set of dependencies we are externalizing from the remote client
- The
configure
call, which downloads/attaches all JS/CSS needed for the remote client - Callbacks to check if configuration and auth have occurred yet, as well as methods to get (or wait for) the remote client
- The
NextCapitalComponent
React component for easily rendering embedded UI while managing the configure/auth lifecycle - Some other odds an ends
The remote client contains:
- Code for handling authentication
- The NextCapital API client
- Any NextCapital embedded UIs
- Any NextCapital Client-specific services
Overall, we expect the local client to be quite stable. Updates should be infrequent and will be clearly communicated. We expect that some updates will be mandatory (major version changes). See the section below for more.
The remote client will update automatically with the NextCapital deployment schedule (every two weeks or so). In this way, partners will automatically receive bug fixes, new features, etc. that will match NextCapital-hosted applications.
The local client is strongly semantically versioned. The local and remote clients are tied together and guaranteed to be compatible with each other. As long as partners always use the latest published major version of the local client, everything will remain compatible with production-deployed NextCapital backend APIs.
However, the older major versions of the local/remote clients are NOT guaranteed to be compatible with the production-deployed NextCapital backend API. Thus, major version updates to the local client are mandatory, as the NextCapital Client may stop working if an older version is used that is unsupported and thus incompatible with the production-deployed NextCapital API.
We pledge to:
- Ensure that changes to the remote client remain compatible with the current version of the local client, if possible
- We hope major/mandatory updates will be relatively rare
- Provide at least two weeks notice of any mandatory updates before changes are deployed to production
- Version will be ready on
npm
before the breaking changes reach the UAT environment - Most updates will just require bumping the
npm
version and adjusting to any breaking changes (if any). - The old local/remote client will continue to work for the full support lifecycle (see below)
- Version will be ready on
- Provide guidance on how to migrate, along with a full changelog and updated documentation, for each update
Minor/patch updates are highly encouraged, but not mandatory. The remote client will remain compatible as long as the major version of the local client matches.
- Minor updates will contain backwards-compatible new features (to the interface of the NextCapital client)
- Patch updates will contain backwards-compatible bug fixes (to the interface of the NextCapital client)
NOTE: Due to the nature of the remote client, minor/patch (backwards-compatible) changes that affect it will also be delivered to earlier versions of the local client with the same major version. We still recommend updating the local client before using any minor/patch version features, even if you may technically be able to use them without doing so.
- For the full version history/changelog, see the 'Changelog' document.
- For information on dependencies and interactions of the NextCapital Client with your application, see the
Dependencies and Runtime
document.
When a major version is released, we will support for the old version until (whichever comes first):
- All active partners have upgraded
- Six months have passed
This means you have six months to upgrade to a major version once it is released. This may also mean that multiple versions are supported at once. Our currently supported versions are:
- v2.0 (latest)
We highly encourage partners to test their NextCapital Client integrations against SIT and UAT. The remote client will follow the normal NextCapital deployment process. If an issue comes up, let NextCapital know and we can get it resolved before code hits production!
For more information on this, see the Authentication, Proxies, and Environments
document.
Please only use the publicly documented interface, as this is what will be officially supported and versioned. Please do not use "private" variables and methods.
Due to the nature of JavaScript, some "private" variables/methods are exposed as module exports/etc. These "private" methods will always have a _
prefix (e.g.: _mySecretMethod
). Attempting to make use of these methods and variables could lead to unexpected behavior or cause bugs. These methods are subject to change without notice at any moment.
Have questions are feedback? Need help? Found a problem? Simply contact your NextCapital representative, and we will be glad to help!