Bundle Getting Started
If you would like to get started building your own bundle or customizing you will need to first check out your bundle project. If you're just getting started you'll want to check out the Customer Default Project source code.
In addition you will need the following:
- Node.js (v18.x recommended)
- Yarn (1.22.x)
- Bundle Project Source (e.g. the Customer Default Project)
- Development OAuth Client
- Trusted Domain changes
Development OAuth Client
In order for your bundle to authenticate correctly with your Kinetic Platform you will need to create a valid OAuth Client for it to use. This is how your environment knows to send authentication credentials back to your development server. To set this up you will need to navigate to the OAuth Security tab (Kinetic Management Console > Space > Settings > OAuth Tab):
Name -> Kinetic Bundle - DevDescription -> oAuth Client for client-side bundles in development modeClient ID -> kinetic-bundle-devClient Secret -> <any value>Redirect URI -> http://localhost:3000/app/oauth/callback
The server must also have trusted domains configured in order for your local development server to be allowed to contact your Kinetic Platform. These settings allow the local development server's bundle code to access the platform's API and to embed frames (which is needed for authentication). Navigate to Space Security Tab (Kinetic Management Console > Space > Settings > Security Tab):
Trusted Resource Domain -> http://localhost:3000Trusted Frame Domain -> localhost:3000
From a command line open inside the
bundle directory, run the below commands to start a development server.
$ yarn install$ yarn start
start, you will be prompted to enter a Kinetic Request CE server to connect to.
Once the development server starts up, you can access it at http://localhost:3000. Any changes you make to your local code will then automatically cause the server to reload with your new changes.
For detailed bundle development instructions, please see the Bundle README.
Starting a Custom Bundle
Requirements: GitHub account and knowledge of git.
In order to customize or build your own custom bundle, it is recommended to begin with this project. You can either fork this repository, or create your own new repository and configure this repository as its upstream, by following the instructions below.
Do NOT check the 'Initialize this repository with a README' checkbox. It must remain unchecked so that we can merge in the history from this repository to allow future syncing.
Let's use the repository name
awesome-custom-bundle in the below examples.
- Clone your repository to your local machine and change to the newly cloned repository.
$ git clone https://github.com/<USERNAME>/awesome-custom-bundle.git> Cloning into 'awesome-custom-bundle'...$ cd awesome-custom-bundle
- Set this repository as the upstream in your
awesome-custom-bundlerepository. We'll also update the push upstream url to an invalid value to prevent accidental pushes to the upstream, in case you happen to have access to do so. Finally, running
git remote -vwill show us the configured remotes.
$ git remote add upstream https://github.com/kineticdata/customer-project-default.git --no-tags$ git remote set-url --push upstream no_push$ git remote -v> origin https://github.com/<USERNAME>/awesome-custom-bundle.git (fetch)> origin https://github.com/<USERNAME>/awesome-custom-bundle.git (push)> upstream https://github.com/kineticdata/customer-project-default.git (fetch)> upstream no_push (push)
- Fetch the upstream branches. Then create a branch in your repo by checking out the upstream branch. This will bring over all the code and history from the upstream, allowing you to merge in future changes from the upstream to your local repo. The
--no-trackflag will make sure this branch does not track the upstream, as we'll want it to track origin since we'll be making changes in it. Lastly, we'll push the our master branch to the origin remote.
$ git fetch upstream> From https://github.com/kineticdata/customer-project-default> * [new branch] develop -> upstream/develop> * [new branch] master -> upstream/master$ git checkout -b master upstream/master --no-track$ git push -u origin master> To https://github.com/<USERNAME>/awesome-custom-bundle.git> * [new branch] master -> master
You are now ready to start developing in your custom bundle repository. See the Bundle README for detailed bundle development instructions.
In order to pull the latest changes from the upstream
customer-project-default repository into your custom
awesome-custom-bundle repository, follow the below instructions. You will need to manually resolve any conflicts during the merge.
$ git checkout master$ git fetch upstream$ git merge upstream/master$ git push origin master
- You can use either the master branch (latest stable release) or the develop branch (latest unreleased changes) from the upstream. It is not recommended to use other upstream branches if they exist.
- You can name your local/origin branch whatever you'd like; master was just used in the above examples.
- Once you start customizing your bundle, it will be your responsibility to merge in and resolve any conflicts from the upstream when we make changes to
.├─ artifacts # Contains artifacts generated for the project├─ bundle # Contains the bundle React code│ ├─ packages # Individual packages that define different parts of the bundle│ │ ├─ app # Entry point to the bundle application│ │ ├─ components # Package that allows for overriding common components│ │ └─ ... # Other custom packages may be added│ └─ package.json # Monorepo configuration file└─ plugins # Contains custom plugins for the project
Directory containing artifacts for the project, such as space exports generated from the SDK, or special documentation such as ADRs.
Directory containing all of the bundle code. See the Bundle README for detailed bundle development instructions.
The bundle consists of multiple packages, where each package defines one area of functionality (e.g. service portal package).
The app package is the entry point to the entire bundle, and defines the rendering and authentication wrappers, as well as a default content renderer. This package is rendered when the bundle is loaded, and then in turn renders the content of the other packages as needed.
The components package exists to allow for overriding of common layout components used by other packages. This package is currently a work in progress.
- other packages
The majority of the prebuilt Kinetic packages are deployed to NPM, and are installed into the App package from NPM, so their code isn't part of this bundle. New packages may be added and connected into the App package to provide custom functionality.
Directory containing all of the custom plugins (such as handlers, bridge adapters, etc.) created for the project.