chore: initial commit

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_size = 2
+indent_style = space
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - run: npm i -g --force corepack@latest && corepack enable
+
+      - name: Install dependencies
+        run: npx nypm@latest i
+
+      - name: Lint
+        run: npm run lint
+
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 20
+
+      - run: npm i -g --force corepack@latest && corepack enable
+
+      - name: Install dependencies
+        run: npx nypm@latest i
+
+      - name: Playground prepare
+        run: npm run dev:prepare
+
+      - name: Test
+        run: npm run test

.gitignore

@@ -0,0 +1,56 @@
+# Dependencies
+node_modules
+
+# Logs
+*.log*
+
+# Temp directories
+.temp
+.tmp
+.cache
+
+# Yarn
+**/.yarn/cache
+**/.yarn/*state*
+
+# Generated dirs
+dist
+
+# Nuxt
+.nuxt
+.output
+.data
+.vercel_build_output
+.build-*
+.netlify
+
+# Env
+.env
+
+# Testing
+reports
+coverage
+*.lcov
+.nyc_output
+
+# VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Intellij idea
+*.iml
+.idea
+
+# OSX
+.DS_Store
+.AppleDouble
+.LSOverride
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk

.npmrc

@@ -0,0 +1,2 @@
+shamefully-hoist=true
+strict-peer-dependencies=false

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "eslint.experimental.useFlatConfig": true
+}

AGENTS.md

@@ -0,0 +1,21 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+`src/module.ts` registers the Nuxt module entry point, while `src/runtime` holds runtime composables and server utilities that ship to consuming apps. Bundle artifacts live in `dist/` and are regenerated via the module builder; do not edit them manually. The demo application under `playground/` is the fastest way to validate changes, and `test/` hosts Vitest suites plus fixture Nuxt apps. Keep shared assets (icons, mocks) inside the relevant directory to avoid leaking into the published package.
+
+## Build, Test, and Development Commands
+- `npm run dev:prepare` – stub the module, generate types, and sync the playground for local hacking.
+- `npm run dev` – start the playground Nuxt dev server with live reload.
+- `npm run dev:build` – create a production build of the playground to sanity-check bundling.
+- `npm run lint` / `npm run test` / `npm run test:watch` – run ESLint or Vitest once or in watch mode.
+- `npm run test:types` – run `vue-tsc` type checks for the module and playground.
+- `npm run prepack` / `npm run release` – build distributables and run the automated release pipeline.
+
+## Coding Style & Naming Conventions
+Follow the Nuxt ESLint preset (`eslint.config.mjs`) with 2-space indentation, single quotes, and semicolons auto-managed by the linter. Exported composables use `useX` naming, server handlers use `defineXHandler`, and configuration files stay in lowercase kebab case (e.g., `nuxt.config.ts`). Prefer TypeScript types over interfaces unless extending, and keep runtime utilities side-effect free so they tree-shake cleanly.
+
+## Testing Guidelines
+Vitest powers unit tests under `test/*.test.ts`; mirror the feature path inside `test/fixtures` when a fixture project is required. Name tests after the behavior under test (`feature-name.test.ts`) and keep expectations in Given/When/Then blocks. Run `npm run test:types` before releasing to ensure published d.ts files stay valid. Aim for coverage of new runtime APIs and add integration tests in the playground when logic spans multiple layers.
+
+## Commit & Pull Request Guidelines
+History is empty; start using Conventional Commits (`feat:`, `fix:`, `chore:`) so automated changelog and release tooling stay accurate. Each pull request should include: concise summary, screenshots or CLI output when UX changes, linked issue IDs, and notes on testing performed. Keep PRs focused (one feature or fix), ensure CI scripts run locally before pushing, and request review when the playground reproduces the desired behavior end to end.

README.md

@@ -0,0 +1,84 @@
+<!--
+Get your module up and running quickly.
+
+Find and replace all on all files (CMD+SHIFT+F):
+- Name: My Module
+- Package name: my-module
+- Description: My new Nuxt module
+-->
+
+# My Module
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+My new Nuxt module for doing amazing things.
+
+- [✨ &nbsp;Release Notes](/CHANGELOG.md)
+<!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/my-module?file=playground%2Fapp.vue) -->
+<!-- - [📖 &nbsp;Documentation](https://example.com) -->
+
+## Features
+
+<!-- Highlight some of the features your module provide here -->
+- ⛰ &nbsp;Foo
+- 🚠 &nbsp;Bar
+- 🌲 &nbsp;Baz
+
+## Quick Setup
+
+Install the module to your Nuxt application with one command:
+
+```bash
+npx nuxi module add my-module
+```
+
+That's it! You can now use My Module in your Nuxt app ✨
+
+
+## Contribution
+
+<details>
+  <summary>Local development</summary>
+  
+  ```bash
+  # Install dependencies
+  npm install
+  
+  # Generate type stubs
+  npm run dev:prepare
+  
+  # Develop with the playground
+  npm run dev
+  
+  # Build the playground
+  npm run dev:build
+  
+  # Run ESLint
+  npm run lint
+  
+  # Run Vitest
+  npm run test
+  npm run test:watch
+  
+  # Release new version
+  npm run release
+  ```
+
+</details>
+
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/my-module
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/my-module
+
+[license-src]: https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/my-module
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

eslint.config.mjs

@@ -0,0 +1,20 @@
+// @ts-check
+import { createConfigForNuxt } from '@nuxt/eslint-config/flat'
+
+// Run `npx @eslint/config-inspector` to inspect the resolved config interactively
+export default createConfigForNuxt({
+  features: {
+    // Rules for module authors
+    tooling: true,
+    // Rules for formatting
+    stylistic: true,
+  },
+  dirs: {
+    src: [
+      './playground',
+    ],
+  },
+})
+  .append(
+    // your custom flat config here...
+  )

package.json

@@ -0,0 +1,53 @@
+{
+  "name": "nuxt-can",
+  "version": "1.0.0",
+  "description": "My new Nuxt module",
+  "repository": "your-org/my-module",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.2.1"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.1.0",
+    "@nuxt/eslint-config": "^1.10.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.2.1",
+    "@nuxt/test-utils": "^3.20.1",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.39.1",
+    "nuxt": "^4.2.1",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.8",
+    "vue-tsc": "^3.1.3"
+  }
+}

playground/app.vue

@@ -0,0 +1,8 @@
+<template>
+  <div>
+    Nuxt module playground!
+  </div>
+</template>
+
+<script setup>
+</script>

playground/nuxt.config.ts

@@ -0,0 +1,5 @@
+export default defineNuxtConfig({
+  modules: ['../src/module'],
+  devtools: { enabled: true },
+  myModule: {},
+})

playground/package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "name": "my-module-playground",
+  "type": "module",
+  "scripts": {
+    "dev": "nuxi dev",
+    "build": "nuxi build",
+    "generate": "nuxi generate"
+  },
+  "dependencies": {
+    "nuxt": "^4.2.1"
+  }
+}

playground/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../.nuxt/tsconfig.server.json"
+}

playground/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./.nuxt/tsconfig.json"
+}

src/module.ts

@@ -0,0 +1,21 @@
+import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit'
+
+// Module options TypeScript interface definition
+export interface ModuleOptions {
+  0: string
+}
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule',
+  },
+  // Default configuration options of the Nuxt module
+  defaults: {},
+  setup(_options, _nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    // Do not add the extension since the `.ts` will be transpiled to `.mjs` after `npm run prepack`
+    addPlugin(resolver.resolve('./runtime/plugin'))
+  },
+})

src/runtime/plugin.ts

@@ -0,0 +1,5 @@
+import { defineNuxtPlugin } from '#app'
+
+export default defineNuxtPlugin((_nuxtApp) => {
+  console.log('Plugin injected by my-module!')
+})

src/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

test/basic.test.ts

@@ -0,0 +1,15 @@
+import { fileURLToPath } from 'node:url'
+import { describe, it, expect } from 'vitest'
+import { setup, $fetch } from '@nuxt/test-utils/e2e'
+
+describe('ssr', async () => {
+  await setup({
+    rootDir: fileURLToPath(new URL('./fixtures/basic', import.meta.url)),
+  })
+
+  it('renders the index page', async () => {
+    // Get response to a server-rendered page with `$fetch`.
+    const html = await $fetch('/')
+    expect(html).toContain('<div>basic</div>')
+  })
+})

test/fixtures/basic/app.vue

@@ -0,0 +1,6 @@
+<template>
+  <div>basic</div>
+</template>
+
+<script setup>
+</script>

test/fixtures/basic/nuxt.config.ts

@@ -0,0 +1,7 @@
+import MyModule from '../../../src/module'
+
+export default defineNuxtConfig({
+  modules: [
+    MyModule,
+  ],
+})

test/fixtures/basic/package.json

@@ -0,0 +1,5 @@
+{
+  "private": true,
+  "name": "basic",
+  "type": "module"
+}

tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./.nuxt/tsconfig.json",
+  "exclude": [
+    "dist",
+    "node_modules",
+    "playground",
+  ]
+}