Error using PostHog Analytics Module

[brittle flax]

Ubuntu 24.04 LTS
PostgreSQL 17
Node.js v22.18.0
Medusa 2.9.0

https://docs.medusajs.com/resources/infrastructure-modules/analytics/posthog
I created the "src/workflows/track order created. ts" and "src/subscribers/order place. ts" files according to the tutorial, but when running yarn dev, I received the following error message:

///
woo@wooawesome:~/medusa$ yarn dev
{"level":"info","message":"Watching filesystem to reload dev server on file change","timestamp":"2025-08-20 08:39:05"}
info: Skipping instrumentation registration. No register function found.
info: Connection to Redis in module 'event-bus-redis' established
info: Connection to Redis in module 'cache-redis' established
info: Connection to Redis in "locking-redis" provider established
info: Connection to Redis in module 'workflow-engine-redis' established
info: Connection to Redis PubSub in module 'workflow-engine-redis' established
error: Error starting server
error: useQueryGraphStep is not defined
ReferenceError: useQueryGraphStep is not defined
at Object.<anonymous> (/home/woo/medusa/src/workflows/track-order-created.ts:41:30)
at createWorkflow (/home/woo/medusa/node_modules/@medusajs/workflows-sdk/src/utils/composer/create-workflow.ts:150:33)
at Object.<anonymous> (/home/woo/medusa/src/workflows/track-order-created.ts:38:56)
at Module._compile (node:internal/modules/cjs/loader:1688:14)
at Module.m._compile (/home/woo/medusa/node_modules/ts-node/src/index.ts:1618:23)
at node:internal/modules/cjs/loader:1820:10
at Object.require.extensions.<computed> [as .ts] (/home/woo/medusa/node_modules/ts-node/src/index.ts:1621:12)
at Module.load (node:internal/modules/cjs/loader:1423:32)
at Function._load (node:internal/modules/cjs/loader:1246:12)
at TracingChannel.traceSync (node:diagnostics_channel:322:14)
///

I added the following code to the 'src/workflows/track order created. ts' file and ran development mode, but still received an error message:
import { useQueryGraphStep } from "@medusajs/medusa/core-flows";

[agile parcel]

Hello, seems like the docmentation is missing the import. Will add it. But what's the error that you receive now?

[agile parcel]

Please try with the following workflows:

import { createWorkflow } from "@medusajs/framework/workflows-sdk"
import { createStep } from "@medusajs/framework/workflows-sdk"
import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
import { Modules } from "@medusajs/framework/utils"
import { OrderDTO } from "@medusajs/framework/types"

type StepInput = {
  order: OrderDTO
}

const trackOrderCreatedStep = createStep(
  "track-order-created-step",
  async ({ order }: StepInput, { container }) => {
    const analyticsModuleService = container.resolve(Modules.ANALYTICS)

    await analyticsModuleService.track({
      event: "order_created",
      actor_id: order.customer_id,
      properties: {
        order_id: order.id,
        total: order.total,
        items: order.items?.map((item) => ({
          variant_id: item.variant_id,
          product_id: item.product_id,
          quantity: item.quantity,
        })),
        customer_id: order.customer_id,
      },
    })
  }
)

type WorkflowInput = {
  order_id: string
}

export const trackOrderCreatedWorkflow = createWorkflow(
  "track-order-created-workflow",
  ({ order_id }: WorkflowInput) => {
    const { data: orders } = useQueryGraphStep({
      entity: "order",
      fields: [
        "*",
        "customer.*",
        "items.*",
      ],
      filters: {
        id: order_id,
      },
    })
    trackOrderCreatedStep({
      order: orders[0],
    } as unknown as StepInput)
  }
)

[brittle flax]

@agile parcel I'm very sorry, I just came back.
Your new code can run normally without any errors in yarn dev.

I just don't understand why the example in the document mentions the file name as "src/workflows/track-order placed. ts", but the actual file name is "src/workflows/track-order created. ts", and the name defined in the code is also "track-order created".

The src/subscribers/order-plaaced.ts code also references:
import { trackOrderCreatedWorkflow } from "../workflows/track-order-created"

Finally, I noticed that the Resend Notifications Module file name "src/subscribers/order-plated.ts" is exactly the same as the PostHog Analytics Module file name "src/subscribers/order-plated.ts", and the code of the two files is also similar, which is very unfriendly for beginners.
Suggest adding a "module name" directory before the "file name" for differentiation, such as "src/subscribers/Resend/order placed. ts"

I understand that the "SendGrid" notification module is well integrated, but "Resend" has free services.

[brittle flax]

https://docs.medusajs.com/resources/integrations/guides/resend
The above Medusa document link is the Resend tutorial.
On line 43 of the "src/workflows/end order confirmation. ts" code in this document, "to: orders[0].email," an error occurs when using the npx medusa build command.
The following code can run normally:
to: orders[0].email ?? "",
or
to: orders[0].email as string,

After running npx medusa build, the error message is as follows:
///
woo@wooawesome:~/medusa$ npx medusa build
{"level":"info","message":"Starting build...","timestamp":"2025-08-20 13:03:25"}
{"level":"info","message":"Compiling backend source...","timestamp":"2025-08-20 13:03:26"}
{"level":"info","message":"Removing existing ".medusa/server" folder","timestamp":"2025-08-20 13:03:26"}
medusa-config.ts:38:5 - error TS2322: Type 'string' is not assignable to type '/${string}'.

38 path: process.env.ADMIN_PATH || "/app",
~~~~
src/workflows/send-order-confirmation.ts:45:7 - error TS2322: Type 'string | (string & WorkflowDataProperties<string> & WorkflowDataProperties<Maybe<string>> & { config(config: { name?: string | undefined; } & Omit<...>): WorkflowData<...>; }) | null' is not assignable to type '(string | WorkflowData<string>) & string'.
Type 'null' is not assignable to type '(string | WorkflowData<string>) & string'.

45 to: orders[0].email,
~~

node_modules/@medusajs/types/dist/notification/mutations.d.ts:12:5
12 to: string;
~~
The expected type comes from property 'to' which is declared here on type '(CreateNotificationDTO | WorkflowData<CreateNotificationDTO>) & CreateNotificationDTO'

{"level":"info","message":"Compiling frontend source...","timestamp":"2025-08-20 13:03:32"}
{"level":"warn","message":"Backend build completed with errors (6.75s)","timestamp":"2025-08-20 13:03:33"}

[agile parcel]

Hi @brittle flax , regarding the file naming inconsistency, I'll correct the discrepancy. But as for how you structure the files in your project, it's up to you of course whether you put them as instructed in the docs or under the src/subscribers/Resend directory.

As for the type error, I couldn't reproduce it on my side. Maybe it's a mismatch in TypeScript versions. I would advise you to fix the type error shown on your end. However, you can't use the ?? operator within the workflow without transform. Learn more in this document: https://docs.medusajs.com/learn/fundamentals/workflows/constructor-constraints#no-conditional-operators

[brittle flax]

I am very honored to receive your reply.
My last question is about setting the 'path' for Medusa in nginx.
After installing Medusa, I immediately set the reverse proxy for Medusa's "/app", "/admin", "/store", and "/auth" paths in the nginx configuration. However, I still face various errors, most of which I have resolved, but there are two errors that still cannot be resolved.

1: Testing the purchase as a customer, clicking the "Place order" button on the checkout page will "flash" an error code (unable to see the error code clearly), and then jump to the order details page.
The browser developer tool prompts a 404 error (image 1 and image 2).

2: Unable to log in to the admin dashboard. Open the admin login page in the browser, enter the username and password, and click the login button without any response. Developer Tool Tip 401 Error (Image 3 and Image 4).

@agile parcel I think it may be an nginx configuration error, but I cannot find the correct reference. Can you help me check my nginx configuration file?

@agile parcel nginx configuration file：

The following is the code for the medusa-config.ts file and env file:

[brittle flax]

@agile parcel I have been trying to solve the above problem, but so far I have no way because I cannot determine if it is an error in nginx or elsewhere. So I need your help.
I hope to receive your reply.

[odd marsh]

[404] /us/contact 你是前端路由不存在contact页面 ，401 错误你得让看下控制台什么错误，或者接口401返回什么错误。