Context & Runtime

/**
 * Get Nuxt instance, throws if unavailable
 * @returns Current Nuxt instance
 * @throws Error if no Nuxt context is available
 */
function useNuxt(): Nuxt;

/**
 * Try to get Nuxt instance, returns null if unavailable
 * @returns Current Nuxt instance or null
 */
function tryUseNuxt(): Nuxt | null;

/**
 * Get direct access to Nuxt context with asyncLocalStorage
 * @returns Current Nuxt instance or undefined
 */
function getNuxtCtx(): Nuxt | undefined;

/**
 * Run function within Nuxt context
 * @param nuxt - Nuxt instance to use as context
 * @param fn - Function to run within context
 * @returns Result of function execution
 */
function runWithNuxtContext<T>(nuxt: Nuxt, fn: T): ReturnType<T>;

import { useNuxt, tryUseNuxt, runWithNuxtContext } from "@nuxt/kit";

// Get Nuxt instance (throws if not available)
export function myUtility() {
  const nuxt = useNuxt();
  console.log(`Nuxt version: ${nuxt.options.version}`);
}

// Safely try to get Nuxt instance
export function safeLookup() {
  const nuxt = tryUseNuxt();
  if (nuxt) {
    console.log("Nuxt is available");
  } else {
    console.log("No Nuxt context");
  }
}

// Run code with specific Nuxt context
const result = runWithNuxtContext(nuxtInstance, () => {
  // This code runs with nuxtInstance as context
  const currentNuxt = useNuxt(); // Will return nuxtInstance
  return currentNuxt.options.dev;
});

/**
 * Access resolved Nuxt runtime configuration with environment variables applied
 * @returns Runtime configuration object
 */
function useRuntimeConfig(): RuntimeConfig;

/**
 * Update Nuxt runtime configuration
 * @param runtimeConfig - Configuration values to merge
 */
function updateRuntimeConfig(runtimeConfig: Record<string, unknown>): void;

interface RuntimeConfig {
  /** Public runtime config (available on client and server) */
  public: Record<string, any>;
  /** Private runtime config (server-only) */
  private?: Record<string, any>;
  /** App-specific configuration */
  app: AppConfig;
  [key: string]: any;
}

interface AppConfig {
  /** Base URL for the application */
  baseURL?: string;
  /** Application build timestamp */
  buildDate?: string;
  /** Environment name */
  env?: string;
  [key: string]: any;
}

import { useRuntimeConfig, updateRuntimeConfig } from "@nuxt/kit";

// Access runtime configuration
export default defineNuxtModule({
  setup() {
    const config = useRuntimeConfig();
    
    console.log(`API URL: ${config.public.apiUrl}`);
    console.log(`Secret key: ${config.secretKey}`);
    console.log(`Base URL: ${config.app.baseURL}`);
  }
});

// Update runtime configuration
updateRuntimeConfig({
  public: {
    apiVersion: "v2",
    features: {
      newFeature: true
    }
  },
  privateKey: process.env.PRIVATE_KEY
});

// Module with runtime config schema
export default defineNuxtModule({
  setup(options, nuxt) {
    // Add to runtime config
    nuxt.options.runtimeConfig = nuxt.options.runtimeConfig || {};
    nuxt.options.runtimeConfig.public = nuxt.options.runtimeConfig.public || {};
    
    // Add public config
    nuxt.options.runtimeConfig.public.myModule = {
      enabled: options.enabled,
      endpoint: options.endpoint
    };
    
    // Add private config
    nuxt.options.runtimeConfig.myModuleSecret = options.secretKey;
  }
});

# Public config (prefixed with NUXT_PUBLIC_)
NUXT_PUBLIC_API_URL=https://api.example.com
NUXT_PUBLIC_SITE_NAME=My Site

# Private config (prefixed with NUXT_)
NUXT_SECRET_KEY=secret123
NUXT_DATABASE_URL=postgresql://...

# Nested configuration
NUXT_PUBLIC_FEATURES_BETA=true
NUXT_AUTH_GOOGLE_CLIENT_ID=google123

import { useRuntimeConfig } from "@nuxt/kit";

export default defineNuxtModule({
  setup() {
    const config = useRuntimeConfig();
    
    // Access public config (available on client)
    const apiUrl = config.public.apiUrl; // NUXT_PUBLIC_API_URL
    const siteName = config.public.siteName; // NUXT_PUBLIC_SITE_NAME
    
    // Access private config (server-only)
    const secretKey = config.secretKey; // NUXT_SECRET_KEY
    const dbUrl = config.databaseUrl; // NUXT_DATABASE_URL
    
    // Access nested config
    const betaFeatures = config.public.features.beta; // NUXT_PUBLIC_FEATURES_BETA
    const googleClientId = config.auth.google.clientId; // NUXT_AUTH_GOOGLE_CLIENT_ID
  }
});

/**
 * Direct access to Nuxt global context (deprecated)
 * @deprecated Use useNuxt() instead
 */
const nuxtCtx: any;

interface Nuxt {
  /** Nuxt configuration options */
  options: NuxtOptions;
  /** Hook system */
  hooks: Hookable;
  /** Hook registration method */
  hook: Hookable['hook'];
  /** Hook calling method */
  callHook: Hookable['callHook'];
  /** Ready promise */
  ready: () => Promise<void>;
  /** Cleanup method */
  close: () => Promise<void>;
  /** Module container */
  moduleContainer?: any;
  /** Server instance */
  server?: any;
  /** Renderer instance */
  renderer?: any;
  [key: string]: any;
}

interface NuxtOptions {
  /** Development mode flag */
  dev: boolean;
  /** Server-side rendering flag */
  ssr: boolean;
  /** Application directory */
  srcDir: string;
  /** Build directory */
  buildDir: string;
  /** Root directory */
  rootDir: string;
  /** Runtime configuration */
  runtimeConfig: RuntimeConfig;
  /** Application configuration */
  app: AppConfig;
  [key: string]: any;
}