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.

Requirements

In addition you will need the following:

• Node.js (v18.x recommended)
• Yarn (1.22.x)
• Knowledge of React and JavaScript
• 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 - Dev
Description   ->  oAuth Client for client-side bundles in development mode
Client ID     ->  kinetic-bundle-dev
Client Secret ->  <any value>
Redirect URI  ->  http://localhost:3000/app/oauth/callback

Trusted Domains

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:3000
Trusted Frame Domain      ->    localhost:3000

Quick Start

From a command line open inside the bundle directory, run the below commands to start a development server.

$ yarn install
$ yarn start

Upon 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.

1. Create a Github repository.

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.

2. 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

3. Set this repository as the upstream in your awesome-custom-bundle repository. 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 -v will 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)

4. 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-track flag 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

Notes

• 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 customer-project-default.

Folder Structure

.
  ├─ 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

• artifacts

Directory containing artifacts for the project, such as space exports generated from the SDK, or special documentation such as ADRs.

• bundle

  Directory containing all of the bundle code. See the Bundle README for detailed bundle development instructions.

  • packages

    The bundle consists of multiple packages, where each package defines one area of functionality (e.g. service portal package).

    • app

    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.

    • components

    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.

• plugins

Directory containing all of the custom plugins (such as handlers, bridge adapters, etc.) created for the project.