Skip to main content

Get Started with React + Fit.js Extensions

The Node + React.js + Fit.js template builds an extension with a React frontend, an Express-based Node.js backend, and Fit.js — the standard library for conventions shared across Fynd Node.js applications. Unlike the SQLite-backed templates, this one stores data in MongoDB and Redis, so both must be running before you preview the extension.

This page covers:

  1. Install and start MongoDB and Redis
  2. Generate the extension
  3. Configure the environment
  4. Preview the extension

Prerequisites​

RepositoryAzure DevOps projectWhy it is needed
fit.jsCommonLibrariesThe Fit.js library
fdk-extension-javascriptJCPLibrariesExtension helper library
fdk-client-javascriptJCPLibrariesPlatform API client
warning

fit.js lives in the CommonLibraries project, not JCPLibraries. Read access to JCPLibraries alone is not enough — npm install fails on the fit dependency without access to CommonLibraries as well.

1. Install and start MongoDB and Redis​

The template will not boot without both services. Installing them is not enough — they must also be started, and most package managers do not start them for you.

Pick the tab for your setup:

Works identically on macOS, Linux, and Windows, and keeps the two containers isolated from any other MongoDB or Redis you have installed.

docker run -d --name fynd-mongo -p 27017:27017 mongo:7
docker run -d --name fynd-redis -p 6379:6379 redis:7

Both containers restart with docker start fynd-mongo fynd-redis after a reboot.

Verify both are running​

nc -z localhost 27017 && echo "mongo up" || echo "mongo DOWN"
nc -z localhost 6379  && echo "redis up" || echo "redis DOWN"

You should see mongo up and redis up. Anything else — including no output at all — means that service is not listening; go back and start it before continuing.

If nc is not installed, the database clients give an equivalent check:

redis-cli ping                              # → PONG
mongosh --quiet --eval 'db.runCommand({ ping: 1 })'   # → { ok: 1 }
note

The template's .env.example expects MongoDB on localhost:27017 and Redis on localhost:6379. If yours run elsewhere, adjust the connection strings in step 3.

2. Generate the extension​

  1. Log in to your Fynd Partner account:

    fdk login --host <HOST_URL>

  2. Initialize the extension from the React + Fit.js template:

    fdk extension init --template node-react-fit

  3. Enter a name for your extension and select the extension type.

note

The --template node-react-fit flag selects Node + React.js + Fit.js(Redis + Mongo) directly, skipping the interactive stack picker. Omit the flag to choose from the full template list.

The frontend is a Git submodule. If the frontend directory is empty after initialization, populate it manually:

git submodule update --init --recursive

3. Configure the environment​

  1. Copy the example environment file:

    cp .env.example .env

  2. Set the database connection strings in .env:

    MONGO_TEMP_EXAMPLE_READ_WRITE=mongodb://localhost:27017/temp-example
    REDIS_TEMP_EXAMPLE_READ_WRITE=redis://localhost:6379
    REDIS_TEMP_EXAMPLE_READ_ONLY=redis://localhost:6379
note

Leave EXTENSION_API_KEY, EXTENSION_API_SECRET, and EXTENSION_BASE_URL commented out. The FDK CLI sets these for you during fdk extension preview.

4. Preview the extension​

  1. Start the preview:

    fdk extension preview

  2. Copy the preview URL from your terminal into the browser and click Accept and Continue.

note

fdk populate is optional. Run it if you want sample products, orders, and other test data in your development company — it is not required to preview the extension.

fdk populate

To run the server directly instead, use npm start (which runs nodemon index.js).

Template dependencies​

The template pins each Fynd library to a specific tag:

DependencyPinned versionSource
fdk-extension-javascriptv1.4.0JCPLibraries
fdk-client-javascriptv1.10.7-24JCPLibraries
fitv3.3.0CommonLibraries/fit.js
warning

Do not replace these Git dependencies with public npm packages. The @gofynd/* packages on the public npm registry are separate release lines and are not compatible with JCP.

Update the client and extension libraries​

The tags above are whatever the template shipped with. They are not necessarily the right versions for the Fynd Commerce version your development company runs on, so check the compatibility matrix before you start building.

1. Look up the compatible versions​

Compatible SDKs lists every FDK Extension Library release alongside the Fynd Commerce version and the fdk-client-javascript version it is built against. Open the FDK Extension Libraries section and read the row for JavaScript.

note

Log in to Azure DevOps first — the version links on that page point into JCPLibraries and will not resolve otherwise.

2. Pin the versions​

Install both libraries at the tags you found, replacing the versions below:

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

To list what tags actually exist on either repository:

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

Always pin a tag. Installing without #vX.Y.Z resolves to the repository's default branch, which trails the release tags.

3. Verify​

npm ls @gofynd/fdk-extension-javascript fdk-client-javascript

The reported versions should match the pair from the compatibility matrix. For more on installing this library on its own — including the express requirement and the package rename at v1.3.0 — see Install FDK Extension Library for JavaScript.

warning

Keep the two versions in step. A fdk-client-javascript that is newer or older than the extension library expects fails at call time — typically as a missing method on a platform client, or a 4xx from an API path that no longer exists on your Fynd Commerce version.

Run with Docker​

docker build -t extension .
docker run -p 8080:8080 extension
note

Docker reads configuration from .env, so complete step 3 first. When running in a container, localhost in the Mongo and Redis URLs refers to the container itself — point them at your host or a linked service instead.

Troubleshooting​

SymptomCause
npm install fails on the fit dependencyNo read access to the CommonLibraries project, which is separate from JCPLibraries.
The frontend directory is emptyThe Git submodule was not initialized. Run git submodule update --init --recursive.
Submodule clone prompts for credentialsThe submodule uses an SSH URL. Register an SSH key with Azure DevOps.
nc -z localhost 6379 prints nothing, or prints redis DOWNRedis is installed but was never started. brew install and apt install do not start a service. Run brew services list (macOS) or systemctl status redis-server (Linux) — if it shows none, stopped, or inactive, start it as shown in step 1.
nc: command not foundnetcat is not installed. Use the redis-cli ping and mongosh checks in step 1 instead.
Connection refused on startupMongoDB or Redis is not running, or the URLs in .env point to the wrong host or port.
EXTENSION_API_KEY is undefinedThe extension was started directly rather than through fdk extension preview, which injects these values.
A platform client method is missing, or an API call returns 4xx unexpectedlyfdk-extension-javascript and fdk-client-javascript are pinned to versions that do not match each other or your Fynd Commerce version. Check Compatible SDKs and re-pin both, as shown in Update the client and extension libraries.

Was this section helpful?