Skip to content

Building an extension for Tapis UI

Jump to bottom
Nathan Dean Freeman edited this page Oct 4, 2024 · 17 revisions

TapisUI comes furnished with a set of tools to aid developers in building extensions onto TapisUI. Each extension with their customizations will be rendered for all configured base urls in the core TapisUI deployment. NOTE: It is not necessary to build an extension if you are running a serverless deployment of TapisUI as you already have complete control to customize your fork as you see fit.

Extensions can be developed directly in TapisUI in the packages directory or as an external package directly installed in TapisUI core.

The how-to below will cover how to develop a package directly in TapisUI

Getting Started

1. Clone or fork TapisUI

If you are cloning the repository, checkout and pull the dev branch, then cut a new branch from this for you extension following the pattern feature/<MY_EXTENSION_NAME_HERE>. Push this branch up to the repository. This will be merged into dev by one of the core developer of TapisUI later. Next, create draft PR here that merges into the dev branch.

2. Create a directory for you package

Copy the example-extension directory in packages directory and rename it to the name of your extension. The directory name MUST be in kebab-case.

3. Prepare your package

Go through the `package.json in your extension directory and ensure you add the name of your extension and any other information you deem relevant.

Replace the following values in your package.json with the appropriate values for your project:

  • <YOUR_PACKAGE_NAME>
  • <YOUR_PACKAGE_VERIONS>
  • <YOUR_NAME>
{
  "name": "<YOUR_PACKAGE_NAME>",
  "version": "<YOUR_PACKAGE_VERIONS>",
  "description": "",
  "main": "./dist/index.js",
  "typings": "./dist/index.d.ts",
  "types": "./dist/index.d.ts",
  "scripts": {
    "clean": "rm -rf dist",
    "test": "echo \"Error: no test specified\" && exit 1",
    "push": "npm run build && npm publish --access public",
    "copy-files": "copyfiles -u 1 \"src/styles/**/*\" \"src/fonts/**/*\" \"src/**/*.scss\" \"src/index.css\" \"src/**/*.css\" \"src/**/*.module.css\" dist/",
    "build": "npm run clean && npx tsc --build ./tsconfig.json && npm run copy-files"
  },
  
  "keywords": [
    "typescript",
    "tapisui"
  ],
  "author": "<YOUR_NAME>",
  "license": "MIT",
  "dependencies": {
    "@tapis/tapis-typescript": "^0.0.51",
    "@tapis/tapisui-extensions-core": "file:../tapisui-extensions-core",
    "@tapis/tapisui-common": "file:../tapisui-common",
    "@tapis/tapisui-hooks": "file:../tapisui-hooks",
    "copyfiles": "^2.4.1",
    "react": "^18.3.1"
  },
  "devDependencies": {
    "@types/node": "^18.19.33",
    "typescript": "^4.9.5",
    "@tapis/tapisui-extension-devtools": "file:../tapisui-extension-devtools",
    "sass": "^1.77.6"
  }
}

4. Modify the index.ts

Go to your package's index.ts file located in the /packages/<YOUR_PACKAGE_NAME>/src directory. Make any modifications you like there and save the file.

5 Register your package

Add your extension mapping to the registeredExtensions object found in the /packages/tapisui-extensions-core/src/registeredExtensions.ts file. The keys of the object are the exact name of the packages to be installed. The value for this key will be an object with a property baseUrls. This is an array of tenant-specific baseUrls (strings) for which you want your extension to be rendered.

It will look something like the following:

export const registeredExtensions: RegisteredExtensions = {
  // ... Other packages
  '<YOUR_PACKAGE_NAME>': {
    baseUrls: [
      'https://<YOUR_TENANT>.tapis.io',
      'https://<ANOTHER_TENANT>.tapis.io'
    ],
  }
  // An of a real extension running in TapisUI currently
  '@icicle/tapisui-extension': {
    baseUrls: [
      'https://icicle.tapis.io',
      'https://icicleai.tapis.io',
      'https://icicle.develop.tapis.io',
      'https://icicleai.develop.tapis.io',
      'https://icicle.staging.tapis.io',
      'https://icicleai.staging.tapis.io',
    ],
  },
};

6. Add the new package to the project's root packages.json file.

Add an entry in the dependencies object with a file reference. It will look something like the folloing: "<YOUR_PACKAGE_NAME>": "file:./packages/<YOUR_PACKAGE_DIRECTORY>"

7. Run the project initializer

Run npm run init-project from the root of the entire project, this will build and install the new package and all other packages that are required. Once this is finished, you can stop the current local server and then run npm run dev. This will start a server with a hotloader watching the files in the /packages directory for changes which will trigger automatic builds for your packages. This means that you will be able to see updates to your package live in the browser.

8. Push and PR

Once you are finished, push your branch up to source control and convert your draft PR in to a real PR and submit it. NOTE It should be merging into the dev branch only.

NOTE Core TapisUI developers have the final say about which extensions are rendered for which tenants/baseUrls. You PR may be turned down if you are trying to render your extension for a tenant that already has extensions registered. If this is intentional, we (the core devs) will meet with the tenant administrator to get approval for you extension.

Clone this wiki locally