Client Quickstart

Learn how Custom Pages work by writing and deploying your first Custom Page without server code. The page will display the text "Hello World!" in Vault.

In this tutorial, you will learn how to:

• Install the dependencies required to build this example.
• Create the client code for a Custom Page using React.
• Build and deploy your client code to a Vault.
• Create and view your Custom Page in Vault.

Prerequisites

Section link for Prerequisites

To follow this tutorial, you need:

• Node.js and npm installed globally
• A sandbox Vault with full Admin and code permissions

Installing Dependencies

Section link for Installing Dependencies

Start from an empty directory that will be the root of your project. To install dependencies:

1. Create a directory for your client code and this Hello World sample:

   Copy to clipboard

   mkdir client\hello-world && cd client\hello-world

   Copy to clipboard

   mkdir -p client/hello-world && cd client/hello-world

2. Install the Vault npm package:

   Copy to clipboard

   npm install https://vault-web-sdk-releases-public.s3.us-west-2.amazonaws.com/hotfix/25.1.0/veeva-vault-25.1.0-release.1.0.5.tgz

3. Install React and react-dom for the runtime:

   Copy to clipboard

   npm install react react-dom

4. Install esbuild to bundle your code:

   Copy to clipboard

   npm install --save-exact --save-dev esbuild

Developing Client Code

Section link for Developing Client Code

Building a custom page in Vault starts with defining the page using JavaScript. The following client code for this sample project is written in React and produces a <div> element containing the text "Hello World!" Learn more about developing client code.

From your client/hello-world directory:

1. Create a file for your client code in src/hello-world.jsx:

   Copy to clipboard

   mkdir src && echo. > src\hello-world.jsx

   Copy to clipboard

   mkdir src && touch src/hello-world.jsx

2. Add the following code:

   Copy to clipboard

   // src/hello-world.jsx import React from 'react'; import { createRoot } from 'react-dom/client'; import { definePage } from '@veeva/vault'; export default definePage(({ element }) => { const root = createRoot(element); root.render( <div>Hello World!</div> ); });

Creating a Manifest File

Section link for Creating a Manifest File

The distribution-manifest.json file describes a client code distribution for your client code. It defines the name of your Custom Page and the path to the built code. Learn more about creating a client code distribution.

From your client/hello-world directory:

1. Create a file named distribution-manifest.json:

   Copy to clipboard

   echo. > distribution-manifest.json

   Copy to clipboard

   touch distribution-manifest.json

2. Add the following to this file:

   1. name: Name of your distribution
   2. pages.name: Name of your page
   3. file: Path to the built (not source) code for your page. You will bundle your source code in the next step.

   Copy to clipboard

   // distribution-manifest.json { "name": "hello_world__c", "pages": [ { "name": "hello_world__c", "file": "dist/hello-world.js" } ] }

Building Your Client Code

Section link for Building Your Client Code

Before you can deploy your code, you will bundle it using esbuild and package it as a ZIP file.

From your client/hello-world directory:

1. Create a file named esbuild.mjs:

   Copy to clipboard

   echo. > esbuild.mjs

   Copy to clipboard

   touch esbuild.mjs

2. Add the following to this file to specify the source file containing your page export and define how your code is bundled:

   Copy to clipboard

   // esbuild.mjs import * as esbuild from 'esbuild'; await esbuild.build({ entryPoints: ['src/hello-world.jsx'], bundle: true, sourcemap: true, outdir: 'dist', format: 'esm', });

3. Build your code using esbuild:

   Copy to clipboard

   node esbuild.mjs

4. Zip the directory that contains your bundled code, and include the distribution manifest file:

   Copy to clipboard

   7z a -tzip hello-world.zip dist distribution-manifest.json

   Copy to clipboard

   zip -rq hello-world.zip dist distribution-manifest.json

Deploying Your Client Code

Section link for Deploying Your Client Code

Now, it’s time to deploy your client code distribution to Vault using Vault API.

From your hello-world directory:

1. Obtain a valid API Session ID.

2. Upload the distribution ZIP using Vault API. This example uses cURL:

   Copy to clipboard

   curl -L https://%HOST%/api/v25.1/uicode/distributions ^ -H "Authorization: $SESSION_ID" ^ -F "file=@hello-world.zip"

   Copy to clipboard

   curl -L https://$HOST/api/v25.1/uicode/distributions \ -H "Authorization: $SESSION_ID" \ -F "file=@hello-world.zip"

3. Create a Page component in the Vault configuration using MDL. This example uses cURL:

   Copy to clipboard

   curl -L https://%HOST%/api/mdl/execute ^ -H "Content-Type: text/plain;" ^ -H "Authorization: $SESSION_ID" ^ -d "RECREATE Page hello_world__c (label('Hello World'),url_path_name('hello-world'),page_client_code('Pageclientcode.hello_world__c'),client_distribution('Clientdistribution.hello_world__c'));"

   Copy to clipboard

   curl -L https://$HOST/api/mdl/execute \ -H "Content-Type: text/plain;" \ -H "Authorization: $SESSION_ID" \ -d 'RECREATE Page hello_world__c ( label('\''Hello World'\''), url_path_name('\''hello-world'\''), page_client_code('\''Pageclientcode.hello_world__c'\''), client_distribution('\''Clientdistribution.hello_world__c'\'') );'

Viewing Your Custom Page

Section link for Viewing Your Custom Page

View your Page at: https://$HOST/ui/#custom/page/hello-world. You should see “Hello World!” printed below your Vault’s navigation bar.

Congratulations! You built your first Custom Page client code from scratch!

Next Steps

Section link for Next Steps

Continue to the server quickstart to add Vault Java SDK server code to your Hello World project.