feat: auto-changeset on push and update documentation

- Workflow auto-creates patch changeset when none exists
- Add OAuth2 authentication docs
- Add attachments docs (file, buffer, inline images)
- Add custom headers and reply-to docs
- Add Docker deployment guide
- Add webpack/bundler troubleshooting
- Add third-party transports docs
- Clarify preview behavior and template paths

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: juandav

.github/workflows/release.yml

@@ -38,19 +38,29 @@ jobs:
       - name: Run tests
         run: pnpm run test --filter=@nestjs-modules/mailer
 
-      - name: Create Release Pull Request
+      - name: Auto-create changeset if none exists
+        run: |
+          CHANGESETS=$(ls .changeset/*.md 2>/dev/null | grep -v README.md || true)
+          if [ -z "$CHANGESETS" ]; then
+            echo "No changesets found, creating auto patch changeset..."
+            cat > .changeset/auto-release.md << 'CHANGESET'
+          ---
+          '@nestjs-modules/mailer': patch
+          ---
+
+          Auto-release patch version with latest changes.
+          CHANGESET
+          fi
+
+      - name: Create Release Pull Request or Publish
         id: changesets
         uses: changesets/action@v1
         with:
+          publish: pnpm run release
           version: pnpm run version-packages
           title: 'chore(release): version packages'
           commit: 'chore(release): version packages'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Publish to npm
-        if: steps.changesets.outputs.hasChangesets == 'false'
-        working-directory: packages/mailer
-        run: npm publish --provenance --access public
-        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

apps/website/docs/advanced.md

@@ -38,6 +38,64 @@ MailerModule.forRootAsync({
 })
 ```
 
+## Third-Party Transports
+
+You can use any Nodemailer-compatible transport plugin:
+
+```typescript
+import * as sendgridTransport from 'nodemailer-sendgrid';
+
+MailerModule.forRoot({
+  transport: sendgridTransport({ apiKey: 'SG.xxxx' }),
+  defaults: {
+    from: '"App" <noreply@example.com>',
+  },
+})
+```
+
+Other popular transports:
+- `nodemailer-sendgrid` — SendGrid API
+- `nodemailer-mailgun-transport` — Mailgun API
+- `nodemailer-ses-transport` — AWS SES (also built-in via Nodemailer)
+
+## Docker Deployment
+
+When deploying with Docker, ensure templates are included in the image:
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile --prod
+
+COPY dist/ ./dist/
+COPY templates/ ./templates/
+
+CMD ["node", "dist/main.js"]
+```
+
+:::tip
+- Use **absolute paths** for template directories in production
+- Set SMTP credentials via environment variables, not hardcoded values
+- If using `preview: true`, disable it in production environments
+:::
+
+## Webpack / Custom Bundlers
+
+If you bundle your NestJS app with webpack, the `@css-inline/css-inline` WASM binary may not be included. This is handled automatically in v2.1.x+ via lazy-loading — the binary is loaded at runtime from `node_modules` instead of at build time.
+
+If you still encounter issues, exclude it from your webpack config:
+
+```javascript
+// webpack.config.js
+module.exports = {
+  externals: {
+    '@css-inline/css-inline': 'commonjs @css-inline/css-inline',
+  },
+};
+```
+
 ## Monorepo Structure
 
 This project is organized as a monorepo using [pnpm workspaces](https://pnpm.io/workspaces) and [Turborepo](https://turbo.build/):

apps/website/docs/configuration.md

@@ -51,6 +51,30 @@ MailerModule.forRoot({
 })
 ```
 
+## OAuth2 Authentication
+
+Use Gmail or other providers with OAuth2:
+
+```typescript
+MailerModule.forRoot({
+  transport: {
+    service: 'gmail',
+    auth: {
+      type: 'OAuth2',
+      user: 'your-email@gmail.com',
+      clientId: 'CLIENT_ID',
+      clientSecret: 'CLIENT_SECRET',
+      refreshToken: 'REFRESH_TOKEN',
+    },
+  },
+  defaults: {
+    from: '"App Name" <your-email@gmail.com>',
+  },
+})
+```
+
+See [Nodemailer OAuth2 docs](https://nodemailer.com/smtp/oauth2/) for details on setting up OAuth2 credentials.
+
 ## Async Configuration
 
 Use `forRootAsync()` to load config from environment or external services:
@@ -92,16 +116,23 @@ export class AppModule {}
 
 ## Multiple Transporters
 
-Configure multiple SMTP servers and switch between them per message:
+Configure multiple SMTP servers with different credentials and switch between them per message:
 
 ```typescript
 MailerModule.forRoot({
   transports: {
-    primary: 'smtps://user@domain.com:pass@smtp.domain.com',
+    primary: {
+      host: 'smtp.example.com',
+      port: 587,
+      auth: { user: 'primary@example.com', pass: 'pass1' },
+    },
     secondary: {
       host: 'smtp.other.com',
       port: 587,
-      auth: { user: 'user', pass: 'pass' },
+      auth: { user: 'secondary@other.com', pass: 'pass2' },
+    },
+    ses: {
+      SES: { /* AWS SES config */ },
     },
   },
   defaults: {
@@ -125,6 +156,8 @@ await this.mailerService.sendMail({
 });
 ```
 
+All transport types are supported for additional transporters: SMTP, SES, Sendmail, Stream, JSON, and custom transports.
+
 ## Dynamic Transporters
 
 Add transporters at runtime using `addTransporter()`:
@@ -135,6 +168,14 @@ this.mailerService.addTransporter('custom', {
   port: 587,
   auth: { user: 'user', pass: 'pass' },
 });
+
+// Use immediately
+await this.mailerService.sendMail({
+  transporterName: 'custom',
+  to: 'user@example.com',
+  subject: 'Hello',
+  html: '<p>Hello!</p>',
+});
 ```
 
 ## Verify Transporters
@@ -148,6 +189,8 @@ MailerModule.forRoot({
 })
 ```
 
+This checks SMTP connectivity when the module initializes. If verification fails, a warning is logged but the application continues to start.
+
 Or verify programmatically:
 
 ```typescript
@@ -158,6 +201,10 @@ const allReady = await this.mailerService.verifyAllTransporters();
 
 Use `preview-email` to open a preview in the browser during development:
 
+```bash
+pnpm add preview-email
+```
+
 ```typescript
 MailerModule.forRoot({
   transport: {
@@ -177,6 +224,13 @@ MailerModule.forRoot({
 })
 ```
 
+:::note
+- `preview-email` is an **optional** dependency. Install it only if you use this feature.
+- Preview does **not** prevent the email from being sent — it runs alongside sending.
+- Preview may not work in headless environments (Docker, CI servers).
+- You can pass options: `preview: { open: { wait: false } }`.
+:::
+
 ## Copy Templates to `dist`
 
 If your templates are inside `src/`, add them as assets in `nest-cli.json`:
@@ -193,3 +247,7 @@ If your templates are inside `src/`, add them as assets in `nest-cli.json`:
 ```
 
 Use the appropriate extension (`.hbs`, `.pug`, `.ejs`) for your template engine.
+
+:::warning
+Templates are **not** compiled by TypeScript. If you reference templates with `__dirname`, make sure they exist in the `dist` folder at runtime.
+:::

apps/website/docs/sending-emails.md

@@ -64,6 +64,97 @@ await this.mailerService.sendMail({
 });
 ```
 
+:::tip
+When using absolute paths, make sure template files are copied to the `dist` folder at build time. See [Copy Templates to dist](/docs/configuration#copy-templates-to-dist).
+:::
+
+## Attachments
+
+Send emails with file attachments:
+
+```typescript
+await this.mailerService.sendMail({
+  to: 'user@example.com',
+  subject: 'Invoice',
+  html: '<p>Please find your invoice attached.</p>',
+  attachments: [
+    {
+      filename: 'invoice.pdf',
+      path: '/absolute/path/to/invoice.pdf',
+    },
+  ],
+});
+```
+
+### Multiple Attachments
+
+```typescript
+await this.mailerService.sendMail({
+  to: 'user@example.com',
+  subject: 'Report',
+  template: 'report',
+  context: { title: 'Monthly Report' },
+  attachments: [
+    // File from disk
+    { filename: 'report.pdf', path: '/path/to/report.pdf' },
+    // Buffer
+    { filename: 'data.csv', content: Buffer.from('id,name\n1,John') },
+    // String content
+    { filename: 'notes.txt', content: 'Some notes here' },
+    // URL (nodemailer will fetch it)
+    { filename: 'logo.png', path: 'https://example.com/logo.png' },
+  ],
+});
+```
+
+### Inline Images (Embedded)
+
+Embed images directly in the HTML using `cid`:
+
+```typescript
+await this.mailerService.sendMail({
+  to: 'user@example.com',
+  subject: 'Newsletter',
+  html: '<img src="cid:logo" alt="Logo" />',
+  attachments: [
+    {
+      filename: 'logo.png',
+      path: '/path/to/logo.png',
+      cid: 'logo',
+    },
+  ],
+});
+```
+
+See [Nodemailer attachments docs](https://nodemailer.com/message/attachments/) for all options.
+
+## Custom Headers
+
+```typescript
+await this.mailerService.sendMail({
+  to: 'user@example.com',
+  subject: 'Hello',
+  html: '<p>Hello!</p>',
+  headers: {
+    'X-Custom-Header': 'custom-value',
+    'X-Priority': '1',
+  },
+});
+```
+
+## Reply-To and Threading
+
+```typescript
+await this.mailerService.sendMail({
+  to: 'user@example.com',
+  replyTo: 'support@example.com',
+  subject: 'Re: Your ticket',
+  html: '<p>We received your request.</p>',
+  inReplyTo: '<original-message-id@example.com>',
+  references: ['<original-message-id@example.com>'],
+});
+```
+
 ## Using a Specific Transporter
 
 When you have multiple transporters configured, specify which one to use:
@@ -76,3 +167,5 @@ await this.mailerService.sendMail({
   html: '<p>Hello!</p>',
 });
 ```
+
+See [Multiple Transporters](/docs/configuration#multiple-transporters) for setup instructions.