packages/kit/src/context.ts (1)

26-26: 🛠️ Refactor suggestion

Rephrase the deprecation warning for clarity and correct version

The warning message could be phrased more gently and should reflect the correct version in which the deprecation will occur.

Suggested change:

-logger.warn('Using fallback global Nuxt instance. You may be using a @nuxt/kit composable outside of a Nuxt context, this behaviour is deprecated and will be removed in v4.')
+logger.warn('Using fallback global Nuxt instance. Using @nuxt/kit composables outside of a Nuxt context is deprecated and will be removed in v5. Please ensure you are within a proper Nuxt context.')

Also applies to: 50-50

packages/nuxt/test/load-nuxt.test.ts (1)

47-56: Enhance test coverage for multiple Nuxt instances.

Whilst the test verifies concurrent loading, it could be more robust with:

1. Assertions to verify each instance has a unique __name
2. Verification that each instance operates independently
3. Cleanup of instances after the test

 it('load multiple nuxt', async () => {
-  await Promise.all([
+  const [nuxt1, nuxt2] = await Promise.all([
     loadNuxt({
       cwd: repoRoot,
     }),
     loadNuxt({
       cwd: repoRoot,
     }),
   ])
+  expect(nuxt1.__name).toBeDefined()
+  expect(nuxt2.__name).toBeDefined()
+  expect(nuxt1.__name).not.toBe(nuxt2.__name)
+  await Promise.all([nuxt1.close(), nuxt2.close()])
 })

packages/nuxt/src/core/nuxt.ts (2)

54-54: Consider documenting the new __name property.

The new __name property and its usage with asyncNameStorage should be documented to help users understand how multiple Nuxt instances are managed.

Would you like me to generate documentation for the new __name property and its role in multi-instance support?

Also applies to: 62-62, 66-66

---

178-189: Enhance the backward compatibility comment.

The comment "backward compatibility with 3.x" could be more descriptive to explain why and how the global singleton is maintained.

Consider updating the comment to:

-    // backward compatibility with 3.x
+    // Maintain backward compatibility with Nuxt 3.x by setting the first instance as global singleton.
+    // This ensures existing applications continue to work without modifications.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

packages/kit/src/context.ts (1)

6-7: ⚠️ Potential issue

Handle potential null return value from asyncNameStorage.getStore()

Using the non-null assertion operator ! with asyncNameStorage.getStore() may lead to runtime errors if the store is undefined. Consider adding a null check to ensure robustness.

-export const getNuxtCtx = () => getContext<Nuxt>(asyncNameStorage.getStore()!)
+export const getNuxtCtx = () => {
+  const store = asyncNameStorage.getStore()
+  if (!store) {
+    // Handle the undefined case, e.g., throw an error or provide a fallback
+    throw new Error('AsyncLocalStorage store is undefined')
+  }
+  return getContext<Nuxt>(store)
+}

packages/nuxt/test/load-nuxt.test.ts (2)

52-62: Consider enhancing test coverage

While the test correctly verifies concurrent loading and absence of warnings, consider adding assertions to:

1. Verify each instance has a unique __name
2. Confirm each instance is properly initialised
3. Test the context isolation between instances

 it('load multiple nuxt', async () => {
-  await Promise.all([
+  const [nuxt1, nuxt2] = await Promise.all([
     loadNuxt({
       cwd: repoRoot,
     }),
     loadNuxt({
       cwd: repoRoot,
     }),
   ])
   expect(loggerWarn).not.toHaveBeenCalled()
+  expect(nuxt1.__name).not.toBe(nuxt2.__name)
+  expect(nuxt1).toBeDefined()
+  expect(nuxt2).toBeDefined()
+
+  // Test context isolation
+  await nuxt1.run(() => {
+    expect(asyncNameStorage.getStore()).toBe(nuxt1.__name)
+  })
+  await nuxt2.run(() => {
+    expect(asyncNameStorage.getStore()).toBe(nuxt2.__name)
+  })
 })

---

64-81: Improve type safety in test

Instead of using @ts-expect-error for a "random" hook, consider:

1. Using a properly typed test hook
2. Creating a type-safe test hook name constant

+const TEST_HOOK = 'test:context' as const
+
 it('expect hooks to get the correct context outside of initNuxt', async () => {
   const nuxt = await loadNuxt({
     cwd: repoRoot,
   })

-  // @ts-expect-error - random hook
-  await nuxt.hook('test', () => {
+  await nuxt.hook(TEST_HOOK, () => {
     const nuxt = useNuxt()
     expect(asyncNameStorage.getStore()).toBe(nuxt.__name)
   })

   expect(asyncNameStorage.getStore()).toBeUndefined()

-  // @ts-expect-error - random hook
-  await nuxt.callHook('test')
+  await nuxt.callHook(TEST_HOOK)

   expect(loggerWarn).not.toHaveBeenCalled()
 })

packages/schema/src/types/nuxt.ts (1)

90-93: Enhance method documentation

Consider adding more detailed documentation for the run method to explain:

1. Its purpose in managing async context
2. Usage examples
3. Return value expectations

 /**
  * @internal
+ * Executes a function within this Nuxt instance's context.
+ * 
+ * @example
+ * ```ts
+ * await nuxt.run(async () => {
+ *   const ctx = useNuxt() // Gets this instance's context
+ *   await ctx.callHook('my-hook')
+ * })
+ * ```
+ * 
+ * @param fn The function to execute within this context
+ * @returns The return value of the executed function
  */
 run: <T extends (...args: any[]) => any>(fn: T) => ReturnType<T>

packages/nuxt/src/core/nuxt.ts (1)

83-89: Consider adding error handling

The context setup could benefit from error handling to ensure proper cleanup in case of initialization failures.

 nuxt.run(() => {
+  try {
     // Set nuxt instance for useNuxt
     getNuxtCtx().set(nuxt)
     nuxt.hook('close', () => {
       getNuxtCtx().unset()
     })
+  } catch (error) {
+    logger.error('Failed to initialize Nuxt context:', error)
+    throw error
+  }
 })

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro