Astro Integration

@notificator-project/astro connects trusted Astro server workflows to the hosted Notificator API. It provides Astro-friendly server helpers and an optional successful-build integration.

Use it for:

Astro Actions and form workflows
API routes and incoming webhooks
server-rendered pages and middleware
scheduled or queued server tasks
successful production build notifications

The package does not add browser tracking, analytics, or a visual widget.

Requirements

Node.js 20 or newer
Astro 5, 6, or 7
a public_client API key created in the web dashboard or Notificator mobile app
a trusted server runtime, serverless function, or deployment environment

Install

npm install @notificator-project/astro

Store the API key in the server or deployment environment:

NOTIFICATOR_API_KEY=wpnotif_replace_with_your_public_client_key

Do not prefix the variable with PUBLIC_. Astro exposes public environment variables to browser code.

Send from an Astro Action

import { defineAction } from "astro:actions";
import { z } from "astro/zod";
import { createAstroNotifier } from "@notificator-project/astro/server";

const notificator = createAstroNotifier();

export const server = {
  contact: defineAction({
    accept: "form",
    input: z.object({
      name: z.string(),
      email: z.string().email(),
    }),
    handler: async ({ name, email }) => {
      await notificator.notify({
        title: "New contact request",
        body: `${name} submitted the contact form.`,
        severity: "info",
        data: { email },
      });

      return { success: true };
    },
  }),
};

Send from an API route

import type { APIRoute } from "astro";
import { sendNotification } from "@notificator-project/astro/server";

export const POST: APIRoute = async ({ request }) => {
  const deployment = await request.json();

  await sendNotification({
    title: "Deployment complete",
    body: `${deployment.version} is live.`,
    severity: "info",
    data: { version: deployment.version },
  });

  return new Response(null, { status: 204 });
};

An API route needs an Astro server adapter when deployed in on-demand mode. Use the adapter supported by your hosting provider and keep the API key in its server-side environment settings.

Send a successful-build alert

The default Astro integration can send one notification after a successful production build. The feature is disabled until configured.

import { defineConfig } from "astro/config";
import notificator from "@notificator-project/astro";

export default defineConfig({
  integrations: [
    notificator({
      notifyOnBuild: {
        title: "Website build complete",
        body: "The production website was generated successfully.",
        data: { environment: "production" },
      },
    }),
  ],
});

Astro cannot run its completed-build hook when compilation stops early. Add failed-build alerts to CI or the hosting provider instead.

Choose delivery controls

await notificator.notify({
  title: "Order queue needs attention",
  body: "The queue exceeded its warning threshold.",
  severity: "warning",
  sendPush: true,
  sendEmail: true,
  sendMqtt: true,
  deviceId: "optional-owned-device-id",
});

Email follows the account preference unless explicitly supplied. MQTT uses the user-owned broker connection configured in the mobile app.

Security checklist

Import the package only from trusted server-side code.
Never call it from a hydrated component or browser script.
Keep NOTIFICATOR_API_KEY out of source control and logs.
Revoke and replace a key immediately if it is exposed.
Use a separate key for each site and environment.

Troubleshooting

The API key is missing

Confirm NOTIFICATOR_API_KEY is available to the server process or build job, then restart the local development server or trigger a new deployment.

The code runs in the browser

Move the call to an Astro Action, API route, middleware, server-rendered page, or another trusted server workflow. The package intentionally rejects browser execution.

The build succeeds but no alert appears

Confirm notifyOnBuild is configured and the API key is available during the build, not only at runtime. Review the Astro build log for a Notificator warning.