# Proxy Setup

If ad blockers or network policies block the SDK assets, use a proxy on your domain. The SDK supports a `proxy.baseUrl` that routes API calls through your server.

## 1) Configure the SDK

### NPM

```javascript
import { Elements } from '@liquidcommerce/elements-sdk';

const client = await Elements('YOUR_API_KEY', {
  env: 'production',
  proxy: {
    // Must be an ABSOLUTE URL ending with a trailing slash — the SDK resolves
    // each request as `new URL('api' + path, baseUrl)`, so a missing trailing
    // slash drops the last path segment.
    baseUrl: 'https://yoursite.com/api/elements-proxy/',
    // Optional: extra headers merged into every proxied request (e.g. credentials)
    headers: { 'X-My-Auth': '...' }
  }
});
```

### CDN (Next.js example)

```jsx
'use client';

import { useEffect } from 'react';
import { Elements } from '@liquidcommerce/elements-sdk';

export default function ProductPage() {
  useEffect(() => {
    (async () => {
      const client = await Elements('YOUR_API_KEY', {
        env: 'production',
        // Absolute URL with a trailing slash (see note above)
        proxy: { baseUrl: 'https://yoursite.com/api/elements-proxy/' }
      });

      await client.injectProductElement([
        { containerId: 'product', identifier: '00619947000020' }
      ]);
    })();
  }, []);

  return <div id="product"></div>;
}
```

## 2) Create the Proxy Endpoint

Your endpoint should forward requests to the LiquidCommerce Elements API, preserving method, headers, and body.

The SDK does not hardcode the upstream host in the proxy path. Instead, it sends the correct environment-specific upstream base URL in the `X-Liquid-Proxy-Target` request header (along with `X-Liquid-Proxy: true`). Forward to that header value rather than to a literal host — this keeps the proxy environment-agnostic. The SDK calls your proxy at `<baseUrl>/api/<endpoint>`, so the path captured after your proxy mount is exactly the `api/<endpoint>` to append to the target.

### Minimal Express Example

```javascript
import express from 'express';
import fetch from 'node-fetch';

const app = express();
app.use(express.json());

// Proxy is mounted at the path of your proxy.baseUrl ('/api/elements-proxy/').
app.all('/api/elements-proxy/*', async (req, res) => {
  // Upstream base URL the SDK wants this request forwarded to
  // (e.g. https://elements-services-production-948630220003.us-central1.run.app)
  const upstream = req.headers['x-liquid-proxy-target'];
  if (!upstream) {
    return res.status(400).send('Missing X-Liquid-Proxy-Target header');
  }

  // Everything after the proxy mount, e.g. 'api/auth/authenticate'
  const forwardedPath = req.params[0];
  const targetUrl = `${upstream}/${forwardedPath}`;

  const response = await fetch(targetUrl, {
    method: req.method,
    headers: {
      ...req.headers,
      host: new URL(upstream).host
    },
    body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body)
  });

  const data = await response.text();
  res.status(response.status).send(data);
});

app.listen(3000, () => {
  console.log('Proxy listening on port 3000');
});
```

## Notes

- Keep your API key server-side whenever possible.
- Ensure CORS allows your storefront domain to call the proxy.

## Related Docs

- [Installation](../getting-started/installation.md)
- [Client API](../api/client.md)