Developing against a remote server

The examples in this documentation set backendUrl to the Sinequa server. That works when your application is served from that server, and it is the deployed case. In development it usually is not: your application runs on localhost and the server is somewhere else — and then it fails.

The fix is a development proxy, and it is not optional.

Why not just configure CORS

Because the session is a cookie, and cookies are harder than headers.

Two obstacles, and CORS only removes the first:

• CORS. The server must name your origin explicitly. With credentials in play, Access-Control-Allow-Origin: * is rejected by the browser — a wildcard and cookies are mutually exclusive.
• The cookie itself. From localhost to another origin, the session cookie is a third-party cookie. Current browsers restrict those by default, so the requests can succeed while carrying no session at all — which surfaces as a login form that reappears after every successful sign-in.

A proxy sidesteps both: the browser only ever talks to your own origin, so nothing is cross-origin and nothing is third-party.

What has to be proxied

Not just /api. A search interface reaches the server through several paths, and the ones that are easy to forget are precisely the ones whose failure is hard to read.

Miss /assets and previews render unstyled. Miss the redirect paths and a provider sign-in never comes back — the loop guard fires and reports that the callback is not authorised for this application, which is technically true and thoroughly misleading.

The configuration

import basicSsl from "@vitejs/plugin-basic-ssl";
import { defineConfig } from "vite";

/** Everything a search interface reaches on the server, not only /api. */
const PROXIED = ["/api", "/assets", "/xdownload", "/auth/redirect", "/saml/redirect", "/r", "/endpoints"];

const target = "https://<your-sinequa-server>";

export default defineConfig({
  // HTTPS is required, not a precaution: the session cookie is `Secure`, so it is
  // only kept on an https origin. Unlike the Angular CLI, Vite generates no
  // certificate — this plugin does. `npm i -D @vitejs/plugin-basic-ssl`
  plugins: [basicSsl()],

  server: {
    proxy: Object.fromEntries(
      PROXIED.map((path) => [
        path,
        {
          target,
          changeOrigin: true,
          // `false` only for a server with a self-signed certificate.
          secure: true,
          ws: true,
        },
      ]),
    ),
  },
});

[
  {
    "context": [
      "/api",
      "/xdownload",
      "/auth/redirect",
      "/saml/redirect",
      "/r",
      "/endpoints",
      "/assets"
    ],
    "target": "https://<your-sinequa-server>",
    "secure": true,
    "changeOrigin": true,
    "ws": true
  }
]

{
  "projects": {
    "my-app": {
      "architect": {
        "serve": {
          "options": {
            "proxyConfig": "proxy.conf.json",
            "ssl": true
          }
        }
      }
    }
  }
}

import { InjectionToken } from "@angular/core";
import { type AtomicClient, createAtomicClient } from "@sinequa/atomic";

export const SINEQUA = new InjectionToken<AtomicClient>("Sinequa client", {
  factory: () =>
    createAtomicClient({
      app: "<your-app>",
      // No backendUrl: requests stay relative and the proxy forwards them.
      // In production, the application is served by the Sinequa server, so
      // relative URLs are correct there too — the same build works in both.
    }),
});

import basicSsl from "@vitejs/plugin-basic-ssl";
import { defineConfig } from "vite";

/** Everything a search interface reaches on the server, not only /api. */
const PROXIED = ["/api", "/assets", "/xdownload", "/auth/redirect", "/saml/redirect", "/r", "/endpoints"];

const target = "https://<your-sinequa-server>";

export default defineConfig({
  // HTTPS is required, not a precaution: the session cookie is `Secure`, so it is
  // only kept on an https origin. Unlike the Angular CLI, Vite generates no
  // certificate — this plugin does. `npm i -D @vitejs/plugin-basic-ssl`
  plugins: [basicSsl()],

  server: {
    proxy: Object.fromEntries(
      PROXIED.map((path) => [
        path,
        {
          target,
          changeOrigin: true,
          // `false` only for a server with a self-signed certificate.
          secure: true,
          ws: true,
        },
      ]),
    ),
  },
});

Then run the dev server as usual — ng serve, vite — and the application talks only to localhost.

The one build that works everywhere

Omitting backendUrl is not a development-only trick. In production the application is served by the Sinequa server, so relative URLs are already correct. The same build therefore works in both places, and there is no environment switch to get wrong.

Keep backendUrl for the cases that genuinely need it: a second backend on one page, a headless consumer with no origin of its own, or a deployment where CORS is properly configured and the cookie is not an obstacle.

Pitfalls

What's next