Setup @comet/mail package

jamesricky · jamesricky · commit bade9e2cdaa2 · 2025-12-15T11:09:59.000+01:00
This will be used for helper functions for building HTML emails with React, such as the already included `css` helper.
Simple components built with React and/or MJML may also be added in future PRs.
diff --git a/.changeset/mighty-pants-march.md b/.changeset/mighty-pants-march.md
@@ -0,0 +1,8 @@
+---
+"@comet/mail": minor
+---
+
+Add the `css` helper function
+
+Similar to the `css` function provided by styled-components or @mui/material.
+It simply returns the string passed into it but provides CSS syntax highlighting and auto-formatting when using certain IDE plugins, e.g. the "styled-components" plugin in VSCode.
diff --git a/demo/api/package.json b/demo/api/package.json
@@ -37,6 +37,7 @@
         "@apollo/server": "^5.1.0",
         "@as-integrations/express5": "^1.1.2",
         "@comet/cms-api": "workspace:*",
+        "@comet/mail": "workspace:*",
         "@faker-js/faker": "^10.1.0",
         "@kubernetes/client-node": "^1.3.0",
         "@mikro-orm/cli": "^6.4.16",
diff --git a/demo/api/src/products/product-published.mail.ts b/demo/api/src/products/product-published.mail.ts
@@ -1,11 +1,18 @@
 import { MailTemplate, MailTemplateInterface } from "@comet/cms-api";
+import { css } from "@comet/mail";
 import { TranslationService } from "@src/translation/translation.service";
 
 type MailProps = {
     recipient: { name: string; email: string; language: string };
     countProductPublished: "all" | number;
 };
 
+const mailStyles = css`
+    body {
+        font-family: Arial, sans-serif;
+    }
+`;
+
 @MailTemplate()
 export class ProductPublishedMail implements MailTemplateInterface<MailProps> {
     constructor(private readonly translationService: TranslationService) {}
@@ -34,7 +41,7 @@ export class ProductPublishedMail implements MailTemplateInterface<MailProps> {
                     countProductPublished: props.countProductPublished,
                 },
             ),
-            html: intl.formatMessage(
+            html: `<head><style>${mailStyles}</style></head>${intl.formatMessage(
                 {
                     id: "product-published-mail.html-message",
                     defaultMessage:
@@ -51,7 +58,7 @@ export class ProductPublishedMail implements MailTemplateInterface<MailProps> {
                     countProductPublished: props.countProductPublished,
                     p: (...chunks) => `<p>${chunks.join("")}</p>`,
                 },
-            ),
+            )}`,
         };
     }
 
diff --git a/dev-pm.config.ts b/dev-pm.config.ts
@@ -126,6 +126,13 @@ export default defineConfig({
             group: ["site-react", "site-nextjs", "cms"],
         },
 
+        //group mail
+        {
+            name: "mail",
+            script: "pnpm --filter @comet/mail run dev",
+            group: ["mail"],
+        },
+
         //group demo admin
         {
             name: "demo-admin",
diff --git a/knip.json b/knip.json
@@ -70,6 +70,9 @@
             "project": ["./src/**/*.{ts,tsx}"],
             "ignore": ["./src/**/*.generated.ts"]
         },
+        "packages/mail": {
+            "project": ["./src/**/*.{ts,tsx}"]
+        },
         "demo/admin": {
             "entry": ["./src/loader.ts", "./src/**/*.cometGen.{ts,tsx}"],
             "project": ["./src/**/*.{ts,tsx}"],
diff --git a/package.json b/package.json
@@ -14,13 +14,14 @@
         "build:docs": "pnpm build:storybook && pnpm --recursive --filter '@comet/eslint-plugin' --filter '@comet/admin*' --filter '!@comet/admin-generator' --filter 'comet-docs' run build",
         "clean": "pnpm --recursive run clean",
         "copy-project-files": "node copy-project-files.js",
-        "dev": "pnpm dev:admin && pnpm dev:cms && pnpm dev:demo",
+        "dev": "pnpm dev:admin && pnpm dev:cms && pnpm dev:mail && pnpm dev:demo",
         "dev:admin": "dev-pm start @comet-admin",
         "dev:cms": "dev-pm start @cms",
         "dev:cms:admin": "dev-pm start @cms-admin",
         "dev:cms:api": "dev-pm start @cms-api",
         "dev:cms:site-nextjs": "dev-pm start @site-nextjs",
         "dev:cms:site-react": "dev-pm start @site-react",
+        "dev:mail": "dev-pm start @mail",
         "dev:demo": "dev-pm start @demo",
         "dev:demo:admin": "dev-pm start @demo-admin",
         "dev:demo:api": "dev-pm start @demo-api",
diff --git a/packages/mail/.prettierignore b/packages/mail/.prettierignore
@@ -0,0 +1 @@
+lib/
diff --git a/packages/mail/eslint.config.mjs b/packages/mail/eslint.config.mjs
@@ -0,0 +1,16 @@
+import eslintConfigReact from "@comet/eslint-config/future/react.js";
+
+/** @type {import('eslint')} */
+const config = [
+    {
+        ignores: ["lib/**"],
+    },
+    ...eslintConfigReact,
+    {
+        rules: {
+            "@comet/no-other-module-relative-import": "off",
+        },
+    },
+];
+
+export default config;
diff --git a/packages/mail/lint-staged.config.mjs b/packages/mail/lint-staged.config.mjs
@@ -0,0 +1,9 @@
+/**
+ * @filename: lint-staged.config.mjs
+ * @type {import('lint-staged').Configuration}
+ */
+export default {
+    "src/**/*.{ts,tsx,js,jsx,json,css,scss,md}": () => "pnpm lint:eslint",
+    "src/**/*.{ts,tsx}": () => "pnpm lint:tsc",
+    "*.{js,json,md,yml,yaml}": () => "pnpm lint:prettier",
+};
diff --git a/packages/mail/package.json b/packages/mail/package.json
@@ -0,0 +1,39 @@
+{
+    "name": "@comet/mail",
+    "version": "8.10.0",
+    "description": "Helper functions for building HTML emails with React",
+    "type": "commonjs",
+    "main": "lib/index.js",
+    "scripts": {
+        "build": "pnpm run clean && tsc",
+        "clean": "rimraf lib",
+        "dev": "tsc --watch",
+        "lint": "run-p lint:prettier lint:eslint lint:tsc",
+        "lint:ci": "pnpm run lint",
+        "lint:eslint": "eslint --max-warnings 0 src/ **/*.json --no-warn-ignored",
+        "lint:prettier": "pnpm exec prettier --check './**/*.{js,json,md,yml,yaml}'",
+        "lint:tsc": "tsc",
+        "test": "jest --passWithNoTests",
+        "test:watch": "jest --watch"
+    },
+    "devDependencies": {
+        "@comet/eslint-config": "workspace:*",
+        "@types/jest": "^29.5.14",
+        "eslint": "^9.30.1",
+        "jest": "^29.7.0",
+        "npm-run-all2": "^8.0.0",
+        "prettier": "^3.6.2",
+        "typescript": "5.9.3"
+    },
+    "peerDependencies": {
+        "eslint": ">=9",
+        "prettier": ">=3"
+    },
+    "engines": {
+        "node": ">=22.0.0"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org"
+    }
+}
diff --git a/packages/mail/src/index.ts b/packages/mail/src/index.ts
@@ -0,0 +1 @@
+export { css } from "./utils/css";
diff --git a/packages/mail/src/utils/css.ts b/packages/mail/src/utils/css.ts
@@ -0,0 +1,4 @@
+/**
+ * Helper function to enable syntax highlighting & auto-formatting for CSS strings when using certain IDE plugins, e.g. the "styled-components" plugin in VSCode.
+ */
+export const css = (strings: TemplateStringsArray, ...rest: unknown[]): string => String.raw({ raw: strings }, ...rest);
diff --git a/packages/mail/tsconfig.json b/packages/mail/tsconfig.json
@@ -0,0 +1,9 @@
+{
+    "compilerOptions": {
+        "outDir": "lib",
+        "rootDir": "src"
+    },
+    "exclude": ["node_modules", "lib"],
+    "extends": "../../tsconfig.core.json",
+    "include": ["./src"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
