Install FDK Extension Library for JavaScript

The FDK Extension Library for JavaScript (fdk-extension-javascript) handles the extension OAuth flow, session and token storage, API client creation, and webhook subscription, so your extension code can focus on business logic.

note

If you generated your extension with fdk extension init, this library is already wired into the starter code and you do not need to install it manually. Follow the steps below only when adding it to an existing project.

Prerequisites

• Node.js v18 or later
• Git
• Read access to JCPLibraries/fdk-extension-javascript in Azure DevOps, with either a registered SSH key or working HTTPS Git credentials
• An Express-based Node.js project

warning

Install this library only from JCPLibraries. The @gofynd/fdk-extension-javascript package on the public npm registry is a separate release line and is not compatible with JCP — do not install it with npm install @gofynd/fdk-extension-javascript.

1. Install the library

The library is not published to a registry, so install it directly from the Git repository at a specific tag. Replace v1.4.0 with the version you need.

npm install express
npm install "git+https://dev.azure.com/GoFynd/JCPLibraries/_git/fdk-extension-javascript#v1.4.0" --save

warning

express must be installed separately. The library requires it internally but does not declare it in dependencies or peerDependencies, so installing the library on its own fails at import time with Cannot find module 'express'.

If you prefer SSH over HTTPS, use this URL instead:

npm install "git+ssh://git@ssh.dev.azure.com:v3/GoFynd/JCPLibraries/fdk-extension-javascript#v1.4.0" --save

note

The SSH path has no _git/ segment and no .git suffix — those belong only in the HTTPS form. The library's own internal dependencies are fetched over HTTPS as of v1.4.0, so HTTPS Git credentials for dev.azure.com are needed either way.

2. Pick a version

Always pin a tag. The repository's default branch (main) trails the release tags, so installing without a #tag gives you an older version than the latest release.

To list the available tags:

git ls-remote --tags git@ssh.dev.azure.com:v3/GoFynd/JCPLibraries/fdk-extension-javascript

warning

The package name changed between releases. Up to v0.2.x it was the unscoped fdk-extension-javascript; from v1.3.0 onward it is @gofynd/fdk-extension-javascript. Import paths differ accordingly, so check which version your project has pinned before copying code samples.

3. Verify the installation

npm ls @gofynd/fdk-extension-javascript

Expected output for v1.4.0:

└── @gofynd/fdk-extension-javascript@1.4.0

The transitive fdk-client-javascript dependency is pulled from JCPLibraries as well and appears in node_modules/fdk-client-javascript.

4. Import the library

For v1.3.0 and later, use the scoped package name:

const { setupFdk } = require("@gofynd/fdk-extension-javascript/express");
const { MemoryStorage } = require("@gofynd/fdk-extension-javascript/express/storage");

The express/storage subpath exports BaseStorage, MemoryStorage, RedisStorage, and SQLiteStorage.

For v0.2.x, drop the scope:

const { setupFdk } = require("fdk-extension-javascript/express");
const { MemoryStorage } = require("fdk-extension-javascript/express/storage");

note

MemoryStorage is convenient for local development, but sessions are lost on restart and are not shared across instances. Use RedisStorage for production deployments.

For the setupFdk configuration options, see FDK Extension Configuration.

Troubleshooting

Symptom	Cause
Cannot find module 'express'	express was not installed. Run npm install express.
Cannot find module 'fdk-extension-javascript/express'	The installed version is v1.3.0 or later, where the package is scoped. Add the @gofynd/ prefix.
Could not resolve hostname ssh.dev.azure.com:v3	The SSH URL was passed to Git in ssh:// form, where :v3 is read as a port. Use the git+ssh://git@ssh.dev.azure.com:v3/... form shown above.
Repository not found or an authentication prompt	Your SSH key is not registered with Azure DevOps, or you lack read access to JCPLibraries/fdk-extension-javascript.
An older version installs than expected	No tag was pinned, so the default main branch was used. Append #vX.Y.Z.