sender-forms
v1.1.1
Published
Nuxt 3 module for Sender.net form integration
Downloads
89
Maintainers
fmabidReadme
sender-forms
Sender.net integration for Nuxt 3/4 and Vue 3. Injects the Sender universal script into your app and provides a <SenderForm> component so you can render embedded signup forms without copying embed snippets by hand.
Which package do I need?
| Framework | Installation | Setup |
|---|---|---|
| Nuxt 3 / Nuxt 4 | npm install sender-forms | modules: ['sender-forms'] in nuxt.config.ts |
| Vue 3 (Vite, etc.) | npm install sender-forms | app.use(SenderFormsPlugin, { accountId }) in main.ts |
Both ship from the same package — Nuxt users import the default module, Vue users import from sender-forms/vue.
Features
- Injects the Sender.net universal JavaScript snippet into
<head>on every page - Auto-registers
<SenderForm>globally — no manual import needed - Works with popup forms (script-only) and embedded forms (script + component)
- TypeScript-friendly options for both Nuxt and Vue
- Optional
enabledflag — handy for disabling in local or preview environments - SSR-safe Vue plugin (guards against
documentaccess on the server)
Installation
# npm
npm install sender-forms
# pnpm
pnpm add sender-forms
# yarn
yarn add sender-formsNuxt Setup
Register the module
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['sender-forms'],
senderForms: {
accountId: 'your-account-public-id',
},
})That's it. The script is injected into <head> on every page and <SenderForm> is available everywhere with no imports.
With environment variable (recommended)
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['sender-forms'],
senderForms: {
accountId: process.env.NUXT_SENDER_ACCOUNT_ID || '',
},
})# .env
NUXT_SENDER_ACCOUNT_ID=XXXXXXXXXXXXXDisable in non-production environments
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['sender-forms'],
senderForms: {
accountId: process.env.NUXT_SENDER_ACCOUNT_ID || '',
enabled: process.env.NODE_ENV === 'production',
},
})Vue 3 Setup
Import the plugin from the /vue subpath and register it with app.use().
// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import { SenderFormsPlugin } from 'sender-forms/vue'
const app = createApp(App)
app.use(SenderFormsPlugin, {
accountId: 'XXXXXXXXXXXXX',
})
app.mount('#app')<SenderForm> is registered globally — use it in any component without importing it.
With Vite environment variable
// main.ts
app.use(SenderFormsPlugin, {
accountId: import.meta.env.VITE_SENDER_ACCOUNT_ID || '',
})# .env
VITE_SENDER_ACCOUNT_ID=XXXXXXXXXXXXXDisable in development
app.use(SenderFormsPlugin, {
accountId: import.meta.env.VITE_SENDER_ACCOUNT_ID || '',
enabled: import.meta.env.PROD,
})Usage
Embedded forms
Embedded forms need two things: the universal script (handled automatically) and a mount point where the form renders. Use <SenderForm> wherever you want the form to appear:
<template>
<section>
<h2>Subscribe to our newsletter</h2>
<SenderForm form-id="aADzYP" />
</section>
</template>The component renders:
<div style="text-align: left" class="sender-form-field" data-sender-form-id="aADzYP"></div>This is the exact markup from Sender's own embed snippet — the universal script finds it and fills in the form.
Multiple forms on one page? Just drop
<SenderForm>in multiple places with differentform-idvalues.
<template>
<div>
<SenderForm form-id="aADzYP" /> <!-- footer form -->
<SenderForm form-id="bBEzZQ" /> <!-- sidebar form -->
</div>
</template>Popup forms
Popup forms only need the universal script in <head> — Sender handles the rest automatically. Configure the module/plugin with your accountId and you're done. No <SenderForm> needed.
Finding your IDs
Account public ID
This is the ID passed to sender('YOUR_ID') in the universal script.
- Log in to Sender.net
- Go to Settings → API access tokens
- Copy your Account public ID
Form ID
This is the data-sender-form-id value from the embed snippet.
- In Sender, go to Forms and open your embedded form
- Open the Publishing or Embed tab
- Find the embed snippet — the form ID is the value of
data-sender-form-id:<div ... data-sender-form-id="aADzYP"></div> <!-- ^^^^^^ this part -->
API Reference
Nuxt module options (senderForms)
| Option | Type | Default | Description |
|---|---|---|---|
| accountId | string | '' | Sender Account public ID. Required — module skips setup if empty. |
| enabled | boolean | true | Set to false to disable script injection and component registration entirely. |
Vue plugin options (SenderFormsPlugin)
| Option | Type | Default | Description |
|---|---|---|---|
| accountId | string | — | Sender Account public ID. Required — plugin skips setup if empty. |
| enabled | boolean | true | Set to false to disable script injection and component registration entirely. |
<SenderForm> component
| Prop | Type | Required | Description |
|---|---|---|---|
| formId | string | ✅ Yes | Embedded form ID from Sender. Use form-id in templates. |
Registered globally by both the Nuxt module and the Vue plugin — no import needed in your components.
How it works
nuxt.config / app.use()
│
▼
accountId provided?
enabled !== false?
│
├── YES → inject <script> into <head>
│ calls sender('your-account-id')
│ loads cdn.sender.net/universal.js
│
└── register <SenderForm> component globally
│
▼
<div class="sender-form-field"
data-sender-form-id="...">
│
▼
Sender script fills in the formNuxt: script is appended at build time via nuxt.options.app.head.script.
Vue: script is injected at runtime via document.createElement('script') inside install(), with an typeof document !== 'undefined' guard for SSR environments.
Troubleshooting
Form not appearing?
- Check the browser console for errors from
cdn.sender.net - Confirm
accountIdis set correctly — check Settings → API access tokens in Sender - Confirm
form-idon<SenderForm>matches thedata-sender-form-idin your Sender embed snippet - If using
enabled, make sure it evaluates totruein your current environment
Script injected but popup not triggering?
- Popup forms are fully managed by Sender's script. Verify your popup is published and active in the Sender dashboard.
Vue + SSR: script not loading?
- The Vue plugin only injects the script in browser environments. If you need SSR head injection, consider using the
@unhead/vuepackage to add the script tag from within a component'sonMountedhook.
Resources
Development
# Install dependencies
pnpm install
# Generate type stubs
pnpm run dev:prepare
# Develop with the playground (Nuxt)
pnpm run dev
# Build the playground
pnpm run dev:build
# Run ESLint
pnpm run lint
# Run tests
pnpm run test
pnpm run test:watch
# Release new version
pnpm run releaseConfigure the playground in playground/nuxt.config.ts with a test accountId, then use <SenderForm form-id="..." /> in playground/app.vue.
To test the Vue plugin separately, create a plain Vite + Vue 3 app and import from sender-forms/vue.