VTEX Ads JavaScript SDK

Integrate VTEX Ads into your storefront with ease

Packages

This repository is a monorepo powered by pnpm and contains two public npm packages:

Package	Description
@vtex/ads-core	Framework-agnostic SDK to fetch sponsored products from the VTEX Ad Network.
@vtex/ads-react	Thin React layer (Provider + hook) on top of ads-core for an ergonomic DX.

Installation

# pick your favourite package manager
pnpm add @vtex/ads-core              # core only
pnpm add @vtex/ads-react             # React hooks

Both packages are shipped as ES Modules and include TypeScript declarations out of the box.

Quick start

Vanilla JS / TypeScript

import { getAds } from "@vtex/ads-core";

const ads = await getAds({
  account: "fashion",
  region: "aws-us-east-1",
  // see types for all available parameters
});

console.log(ads.byPlacement.homepage);

React

import { AdsProvider, useAds } from "@vtex/ads-react";

export function App() {
  return (
    <AdsProvider account="fashion" region="aws-us-east-1">
      <HomePage />
    </AdsProvider>
  );
}

function HomePage() {
  const { ads, isLoading } = useAds({ placement: "homepage" });

  if (isLoading) return <p>Loading…</p>;
  return <pre>{JSON.stringify(ads, null, 2)}</pre>;
}

Documentation

Comprehensive guides & API reference at https://vtex.github.io/ads-js/docs.

Spin up the playground locally with pnpm playground:dev or try it online at https://vtex.github.io/ads-js/.

Release & Publishing

This repo uses Changesets for versioning and the DK CI/CD npm-publish-v1 pipeline for publishing to npm.

1. Prepare the PR

In your feature branch, create the changeset and version in one go:

pnpm changeset        # describe the change and bump type
pnpm version-packages # bump package.json, update CHANGELOG, delete the changeset file

Open a single PR with everything: code changes, updated package.json, updated CHANGELOG.md.

2. Tag and trigger the pipeline

After the PR is merged, pull main and push a single Git tag for both packages (they are always kept at the same version):

git checkout main && git pull

# Production release
git tag v1.2.3
git push origin v1.2.3

# Beta release
git tag v1.2.3-beta.0
git push origin v1.2.3-beta.0

Pushing the tag triggers two npm-publish-v1 pipelines in parallel — one for ads-core and one for ads-react — which build each package and publish them to AWS CodeArtifact.

3. Publish to npm

After both pipelines complete, the DK automatically triggers the corresponding GitHub Actions workflows:

• Actions → Publish ads-core to npm (publish-core.yml)
• Actions → Publish ads-react to npm (publish-react.yml)

Each workflow reads the version from its own package.json, downloads the tarball from CodeArtifact, and publishes it to npmjs. The CA_TOKEN and CA_OWNER inputs are filled automatically by DK. You can also trigger them manually if needed.

Prerequisite: each package must have a NPM Trusted Publisher configured on npmjs.com pointing to this repo — publish-core.yml for @vtex/ads-core and publish-react.yml for @vtex/ads-react. This is a one-time setup per package.