npm - @alwaysmeticulous/cli - Versions diffs - 2.326.0 → 2.327.0 - Mend

@alwaysmeticulous/cli 2.326.0 → 2.327.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (450) hide show

package/dist/commands/onboard/templates/docs/recorder-snippets/script-based-instructions/next-js-instructions.ts ADDED Viewed

@@ -0,0 +1,49 @@
+import { SNIPPET_URL } from "../constants";
+export const nextJsInstructions = (
+  headTag: "head" | "Head",
+  injectSessionIdHeader = false,
+) => `
+{% code_with_project_selector %}
+{% tabs tabNameSpace="env" %}
+{% tab label="Dev & Staging Only" %}
+\`\`\`jsx
+<${headTag}>
+  ...
+      {(process.env.NODE_ENV === "development" || process.env.VERCEL_ENV === "preview") && (
+        // eslint-disable-next-line @next/next/no-sync-scripts
+        <script
+          data-recording-token="{% project_recording_token /%}"
+          data-is-production-environment="false"${
+            injectSessionIdHeader
+              ? '\n          data-inject-session-id-header="true"'
+              : ""
+          }
+          src="${SNIPPET_URL}"
+        />
+      )}
+  ...
+</${headTag}>
+\`\`\`
+{% /tab %}
+{% tab label="All Environments" %}
+\`\`\`jsx
+<${headTag}>
+  ...
+      // eslint-disable-next-line @next/next/no-sync-scripts
+      <script
+      data-recording-token="{% project_recording_token /%}"
+      data-is-production-environment={process.env.NODE_ENV === "production" || process.env.VERCEL_ENV === "production"}${
+        injectSessionIdHeader
+          ? '\n      data-inject-session-id-header="true"'
+          : ""
+      }
+      src="${SNIPPET_URL}"
+      />
+  ...
+</${headTag}>
+\`\`\`
+{% /tab %}
+{% /tabs %}
+{% /code_with_project_selector %}
+`;

package/dist/commands/onboard/templates/docs/recorder-snippets/script-based-instructions/nuxtjs-instructions.ts ADDED Viewed

@@ -0,0 +1,68 @@
+import {
+  METICULOUS_SETUP_CALENDLY_LINK,
+  METICULOUS_SUPPORT_EMAIL,
+} from "src/lib/next/next.constants";
+import { ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL } from "src/lib/utils/internal-urls/docs-urls.utils";
+// Tested on https://github.com/digitalocean/sample-nuxtjs
+export const nuxtJsInstructions = (
+  injectSessionIdHeader = false,
+) => `Install the Meticulous recorder plugin and add it to your Nuxt config. The plugin injects the recorder script as the first script tag in your app's \`<head>\`, with no async or defer attributes ([learn more](${ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL})).
+{% code %}
+\`\`\`shell
+npm install @alwaysmeticulous/recorder-plugin --save-dev
+\`\`\`
+{% /code %}
+Modify your \`nuxt.config.ts\` file to include the plugin:
+{% code_with_project_selector %}
+{% tabs tabNameSpace="env" %}
+{% tab label="Dev Only (default)" %}
+\`\`\`typescript
+export default defineNuxtConfig({
+  modules: [
+    [
+      "@alwaysmeticulous/recorder-plugin/nuxt",
+      ${
+        injectSessionIdHeader
+          ? `{
+        recordingToken: "{% project_recording_token /%}",
+        attributes: { "data-inject-session-id-header": "true" },
+      }`
+          : `{ recordingToken: "{% project_recording_token /%}" }`
+      },
+    ],
+  ],
+});
+\`\`\`
+{% /tab %}
+{% tab label="All Environments" %}
+\`\`\`typescript
+export default defineNuxtConfig({
+  modules: [
+    [
+      "@alwaysmeticulous/recorder-plugin/nuxt",
+      {
+        recordingToken: "{% project_recording_token /%}",
+        enabled: "always",${
+          injectSessionIdHeader
+            ? '\n        attributes: { "data-inject-session-id-header": "true" },'
+            : ""
+        }
+      },
+    ],
+  ],
+});
+\`\`\`
+{% /tab %}
+{% /tabs %}
+{% /code_with_project_selector %}
+By default, the plugin injects the recorder only during Nuxt development builds. If you set \`enabled: "always"\`, the plugin will inject the recorder in every environment and automatically set \`data-is-production-environment\` based on Nuxt's detected mode.
+By default Meticulous will stub out all requests to server side rendered pages, and so won't test server side rendered content. If you
+use server side rendering and wish to test your server side rendered pages then please reach out to
+[${METICULOUS_SUPPORT_EMAIL}](mailto:${METICULOUS_SUPPORT_EMAIL}), or [book a call with us](${METICULOUS_SETUP_CALENDLY_LINK}), and we'll help you get set up.
+`;

package/dist/commands/onboard/templates/docs/recorder-snippets/script-based-instructions/rsbuild-instructions.ts ADDED Viewed

@@ -0,0 +1,66 @@
+import { ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL } from "src/lib/utils/internal-urls/docs-urls.utils";
+export const rsbuildInstructions = (
+  injectSessionIdHeader = false,
+) => `Install the Meticulous recorder plugin and add it to your rsbuild config. The plugin injects the recorder script as the first script tag in your app's \`<head>\`, with no async or defer attributes ([learn more](${ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL})).
+{% code %}
+\`\`\`shell
+npm install @alwaysmeticulous/recorder-plugin --save-dev
+\`\`\`
+{% /code %}
+Modify your \`rsbuild.config.ts\` file to include the plugin:
+{% code_with_project_selector %}
+{% tabs tabNameSpace="env" %}
+{% tab label="Dev Only (default)" %}
+\`\`\`typescript
+import { defineConfig } from "@rsbuild/core";
+import meticulous from "@alwaysmeticulous/recorder-plugin/rspack";
+export default defineConfig({
+  tools: {
+    rspack: {
+      plugins: [
+        meticulous({
+          recordingToken: "{% project_recording_token /%}",${
+            injectSessionIdHeader
+              ? '\n          attributes: { "data-inject-session-id-header": "true" },'
+              : ""
+          }
+        }),
+      ],
+    },
+  },
+});
+\`\`\`
+{% /tab %}
+{% tab label="All Environments" %}
+\`\`\`typescript
+import { defineConfig } from "@rsbuild/core";
+import meticulous from "@alwaysmeticulous/recorder-plugin/rspack";
+export default defineConfig({
+  tools: {
+    rspack: {
+      plugins: [
+        meticulous({
+          recordingToken: "{% project_recording_token /%}",
+          enabled: "always",${
+            injectSessionIdHeader
+              ? '\n          attributes: { "data-inject-session-id-header": "true" },'
+              : ""
+          }
+        }),
+      ],
+    },
+  },
+});
+\`\`\`
+{% /tab %}
+{% /tabs %}
+{% /code_with_project_selector %}
+By default, the plugin injects the recorder only during non-production rsbuild builds. If you set \`enabled: "always"\`, the plugin will inject the recorder in every environment and automatically set \`data-is-production-environment\` based on Rspack's detected mode.
+`;

package/dist/commands/onboard/templates/docs/recorder-snippets/script-based-instructions/storybook-instructions.ts ADDED Viewed

@@ -0,0 +1,59 @@
+import {
+  METICULOUS_SETUP_CALENDLY_LINK,
+  METICULOUS_SUPPORT_EMAIL,
+} from "src/lib/next/next.constants";
+import {
+  ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL,
+  TYPESCRIPT_TYPES_URL,
+} from "src/lib/utils/internal-urls/docs-urls.utils";
+import { SNIPPET_URL } from "../constants";
+export const storybookInstructions = (
+  injectSessionIdHeader = false,
+) => `If you want to record sessions using Storybook, you can add the Meticulous recorder script tag by
+creating a \`.storybook/preview-head.html\` file and adding the following:
+{% code_with_project_selector %}
+\`\`\`html
+<script
+  data-recording-token="{% project_recording_token /%}"
+  data-is-production-environment="false"${
+    injectSessionIdHeader ? '\n  data-inject-session-id-header="true"' : ""
+  }
+  src="${SNIPPET_URL}"
+></script>
+<script>
+  // Record and replay Storybook events sent from the parent (manager) to the
+  // component iframe. These events capture interactions in Storybook controls
+  // and actions (e.g., switching between stories).
+  if (window.Meticulous?.replay) {
+    window.Meticulous.replay.addCustomEventListener(
+      "storybook-event",
+      (serializedData) =>
+        window.postMessage(serializedData, "*")
+      ,
+    )
+  } else {
+    window.addEventListener("message", event => {
+      // Check if it's a storybook event
+      try {
+        const data = JSON.parse(event.data)
+        if (data.key === "storybook-channel") {
+          if (window.Meticulous?.record) {
+            window.Meticulous.record.recordCustomEvent(
+              "storybook-event",
+              event.data,
+            )
+          }
+        }
+      } catch (e) {
+        // Not a JSON message, ignore
+      }
+    })
+  }
+</script>
+\`\`\`
+{% /code_with_project_selector %}
+For TypeScript type definitions for the \`window.Meticulous\` object, see [TypeScript Types for window.Meticulous](${TYPESCRIPT_TYPES_URL}).
+`;

package/dist/commands/onboard/templates/docs/recorder-snippets/script-based-instructions/sveltekit-instructions.ts ADDED Viewed

@@ -0,0 +1,113 @@
+import {
+  METICULOUS_SETUP_CALENDLY_LINK,
+  METICULOUS_SUPPORT_EMAIL,
+} from "src/lib/next/next.constants";
+import { ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL } from "src/lib/utils/internal-urls/docs-urls.utils";
+import { SNIPPET_URL } from "../constants";
+// Tested on https://github.com/davjhan/guess-the-year-game
+// (note: you need to delete all davjhan-core references, or manually checkout the davjhan-core repo)
+export const svelteKitInstructions = (
+  injectSessionIdHeader = false,
+) => `**(A)** Add the Meticulous recorder script tag in a \`<svelte:head>\` tag at the top of your \`__layout.svelte\` file. It's important the script is the
+first script, and async and defer are not set to true ([learn more](${ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL})):
+{% code_with_project_selector %}
+{% tabs tabNameSpace="env" %}
+{% tab label="Dev & Staging Only" %}
+\`\`\`svelte
+<svelte:head>
+{#if !import.meta.env.PROD}
+  <script
+    data-recording-token="{% project_recording_token /%}"
+    data-is-production-environment="false"${
+      injectSessionIdHeader ? '\n    data-inject-session-id-header="true"' : ""
+    }
+    src="${SNIPPET_URL}"
+  ></script>
+{/if}
+</svelte:head>
+\`\`\`
+{% /tab %}
+{% tab label="All Environments" %}
+\`\`\`svelte
+<svelte:head>
+  <script
+    data-recording-token="{% project_recording_token /%}"
+    data-is-production-environment={import.meta.env.PROD}${
+      injectSessionIdHeader ? '\n    data-inject-session-id-header="true"' : ""
+    }
+    src="${SNIPPET_URL}"
+  ></script>
+</svelte:head>
+\`\`\`
+{% /tab %}
+{% /tabs %}
+{% /code_with_project_selector %}
+**(B)** In your app.html, make sure that \`%svelte.head%\` is above any other scripts in the \`<head>\` tag:
+Good:
+{% code %}
+\`\`\`html
+<head>
+    %svelte.head%
+    <script src="another-script.js"></script>
+</head>
+\`\`\`
+{% /code %}
+Bad:
+{% code %}
+\`\`\`html
+<head>
+    <script src="another-script.js"></script>
+    %svelte.head%
+</head>
+\`\`\`
+{% /code %}
+**(C)** Wire through the MODE environment variable, and make sure MODE is set to \`production\` only for production builds:
+Add \`mode: process.env.MODE || 'development'\` to the \`vite\` section of your \`kit\` config in your \`svelte.config.js\` file. For example:
+{% code %}
+\`\`\`javascript
+const config = {
+  kit: {
+      vite: {
+          // default to development as a guard
+          mode: process.env.MODE || 'development',
+      }
+  },
+}
+\`\`\`
+{% /code %}
+For all builds that get deployed to production, build your application using:
+\`\`\`bash
+MODE=production npm run build
+\`\`\`
+And for all other builds, including builds that get deployed to staging stacks and preview URLs, build your app using:
+\`\`\`bash
+MODE=development npm run build
+\`\`\`
+or
+\`\`\`bash
+MODE=staging npm run build
+\`\`\`
+**(D)** If you want to test your server side rendered content, then contact us
+By default Meticulous will stub out all requests to server side rendered pages, and so won't test server side rendered content. If you
+use server side rendering and wish to test your server side rendered pages then please reach out to
+[${METICULOUS_SUPPORT_EMAIL}](mailto:${METICULOUS_SUPPORT_EMAIL}), or [book a call with us](${METICULOUS_SETUP_CALENDLY_LINK}), and we'll help you get set up.
+`;

package/dist/commands/onboard/templates/docs/recorder-snippets/script-based-instructions/vite-instructions.ts ADDED Viewed

@@ -0,0 +1,58 @@
+import { ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL } from "src/lib/utils/internal-urls/docs-urls.utils";
+export const viteInstructions = (
+  injectSessionIdHeader = false,
+) => `Install the Meticulous recorder plugin and add it to your Vite config. The plugin injects the recorder script as the first script tag in your app's \`<head>\`, with no async or defer attributes ([learn more](${ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL})).
+{% code %}
+\`\`\`shell
+npm install @alwaysmeticulous/recorder-plugin --save-dev
+\`\`\`
+{% /code %}
+Modify your \`vite.config.ts\` file to include the plugin:
+{% code_with_project_selector %}
+{% tabs tabNameSpace="env" %}
+{% tab label="Dev Only (default)" %}
+\`\`\`typescript
+import { defineConfig } from "vite";
+import meticulous from "@alwaysmeticulous/recorder-plugin/vite";
+export default defineConfig({
+  plugins: [
+    meticulous({
+      recordingToken: "{% project_recording_token /%}",${
+        injectSessionIdHeader
+          ? '\n      attributes: { "data-inject-session-id-header": "true" },'
+          : ""
+      }
+    }),
+  ],
+});
+\`\`\`
+{% /tab %}
+{% tab label="All Environments" %}
+\`\`\`typescript
+import { defineConfig } from "vite";
+import meticulous from "@alwaysmeticulous/recorder-plugin/vite";
+export default defineConfig({
+  plugins: [
+    meticulous({
+      recordingToken: "{% project_recording_token /%}",
+      enabled: "always",${
+        injectSessionIdHeader
+          ? '\n      attributes: { "data-inject-session-id-header": "true" },'
+          : ""
+      }
+    }),
+  ],
+});
+\`\`\`
+{% /tab %}
+{% /tabs %}
+{% /code_with_project_selector %}
+By default, the plugin injects the recorder only during Vite development builds. If you set \`enabled: "always"\`, the plugin will inject the recorder in every environment and automatically set \`data-is-production-environment\` based on Vite's detected mode.
+`;

package/dist/commands/onboard/templates/docs/recorder-snippets/script-requirements.ts ADDED Viewed

@@ -0,0 +1,51 @@
+import {
+  ADDITIONAL_GUIDES,
+  INSTALL_RECORDER_AS_NPM_DEPENDENCY_URL,
+  ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL,
+} from "src/lib/utils/internal-urls/docs-urls.utils";
+const REQUIREMENTS_TITLE =
+  "**Important: The Meticulous Recorder script should be the first script to load, and have no async or defer attributes**";
+const NEXTJS_REQUIREMENTS_TITLE =
+  "**Important: The Meticulous Recorder script should use the native `script` tag instead of the NextJS `Script` component, be the first script to load, and have no async or defer attributes**";
+export const DEFAULT_NOT_POSSIBLE_TO_MEET_REQUIREMENTS_TEXT = `If it's not possible to meet these requirements then you can [use an NPM dependency instead of a script tag](${INSTALL_RECORDER_AS_NPM_DEPENDENCY_URL}). If you need to wait for a network request to complete before you know whether you should record the session then you can [buffer the requests in memory, and only send them later](${ADDITIONAL_GUIDES.CONTROLLING_WHEN_RECORDING_STARTS_AND_STOPS_URL}).`;
+export const scriptRequirementsCalloutCard = ({
+  isNextJs,
+  notPossibleToMeetRequirementsText,
+}: {
+  isNextJs: "yes" | "no" | "maybe";
+  notPossibleToMeetRequirementsText?: string;
+}) => `
+{% callout_card showIcon=false %}
+${isNextJs === "yes" ? NEXTJS_REQUIREMENTS_TITLE : REQUIREMENTS_TITLE}
+Libraries you depend on may snapshot references
+to \`window.fetch\` or \`window.XMLHttpRequest\` early in the page lifecycle, which means if Meticulous is not the first script to load
+it may not be able to record all the network
+responses required for your app to function ([learn more](${ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL})). Therefore the recorder script
+must be the first script to load in order to be guaranteed to capture all network requests correctly. This means:
+1. It should be added to your \`index.html\` file, before any other script tags.
+2. It should not have any async or defer attributes set${
+  isNextJs === "yes"
+    ? `, and use the native \`script\` tag instead of the NextJS \`Script\` component`
+    : "."
+}${
+  isNextJs === "maybe"
+    ? ` If using NextJS then it should use the native \`script\` tag instead of the NextJS \`Script\` component.`
+    : ""
+}
+3. It should be present in the initial HTML returned from the server -- you cannot add the script tag dynamically using JavaScript, since if
+you do so the browser may execute the script after other scripts have loaded. If you need to include the script tag in your HTML only
+in certain environments then this must be done either server-side, or at build time by templating your HTML.
+${
+  notPossibleToMeetRequirementsText ??
+  DEFAULT_NOT_POSSIBLE_TO_MEET_REQUIREMENTS_TEXT
+}
+{% /callout_card %}
+`;

package/dist/commands/onboard/templates/docs/recorder-snippets/steps-after-installing-recorder.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import {
+  RECORDER_CSP_EXCEPTIONS_URL,
+  TROUBLESHOOT_RECORDER_URL,
+} from "src/lib/utils/internal-urls/docs-urls.utils";
+export const STEPS_AFTER_INSTALLING_RECORDER = `
+## Validating installation
+Once you add the Meticulous snippet, open your webapp (either locally or on the environment that you injected the snippet into) and record a session by clicking around on your web app.
+If the snippet was installed successfully you should be able to view the recorded session in your
+{% project_link %}Meticulous dashboard {% /project_link %} in the **Sessions** section.
+If you set a CSP policy on your application then you'll need to add [these](${RECORDER_CSP_EXCEPTIONS_URL}) CSP exceptions.
+## I've installed the snippet but why do I not see any sessions in my Meticulous dashboard?
+See [troubleshooting](${TROUBLESHOOT_RECORDER_URL}) for more information on why this might be happening.
+## Issues / questions?
+We're always happy to help you with any issues you encounter while setting up or anything you might be unsure about.
+Get in touch by emailing [support@meticulous.ai](mailto:support@meticulous.ai).
+`;