@nuxt/module-builder 0.1.1 → 0.1.5

package/README.md

@@ -14,9 +14,17 @@
 - Auto generated types and shims for `@nuxt/schema`
 
 
+## Quick start
+
+You can quickly get started with pre-configured [module starter](https://github.com/nuxt/starter/tree/module):
+
+```bash
+$ npx nuxi init -t "nuxt/starter#module" my-module
+```
+
 ## Project structure
 
-Using module builder, requires a special project setup. You can check a full example [here](./example).
+Using module builder, requires a special project setup. You can check an example [here](./example).
 
 ### `src/module.ts`
 
@@ -24,6 +32,8 @@ This is the entrypoint for module definition.
 
 A default export using `defineNuxtModule` and `ModuleOptions` type export is expected.
 
+You could also optionally export `ModuleHooks` to annotate any custom hooks module uses.
+
 ```js [src/module.ts]
 import { defineNuxtModule } from '@nuxt/kit'
 
@@ -31,6 +41,10 @@ export interface ModuleOptions {
   apiKey: string
 }
 
+export interface ModuleHooks {
+  'my-module:init': any
+}
+
 export default defineNuxtModule<ModuleOptions>({
   meta: {
     name: 'my-module',
@@ -85,6 +99,20 @@ A minimum `package.json` should look like this:
 }
 ```
 
+## Dist files
+
+Module builder generates dist files in `dist/` directory:
+
+- `module.mjs`: Module entrypoint build from `src/module`
+- `module.json`: Module meta extracted from `module.mjs` + `package.json`
+- `module.cjs`: ESM proxy to allow require module in CommonJS context
+- `types.d.ts`: Exported types in addition to shims for `nuxt.config` auto completion.
+- `runtime/*`: Individually transformed files using [unjs/mkdist](https://github.com/unjs/mkdist)
+  - Javascript and `.ts` files will be transformed to `.mjs` with extracted types on `.d.ts` file with same name
+  - `.vue` files will be transformed with extracted `.d.ts` file
+  - Other files will be copied as as
+
+
 
 ## 💻 Development
 

package/dist/chunks/build.mjs

@@ -1,11 +1,14 @@
-import { existsSync, promises } from 'fs';
+import { promises, existsSync } from 'fs';
+import { pathToFileURL } from 'url';
 import { resolve } from 'pathe';
 import consola from 'consola';
+import { findExports } from 'mlly';
 
-async function buildModule(rootDir) {
+async function buildModule(opts) {
   const { build } = await import('unbuild');
-  await build(rootDir, false, {
+  await build(opts.rootDir, false, {
     declaration: true,
+    stub: opts.stub,
     entries: [
       "src/module",
       { input: "src/runtime/", outDir: "dist/runtime", ext: "mjs" }
@@ -24,7 +27,7 @@ async function buildModule(rootDir) {
       async "rollup:done"(ctx) {
         await writeCJSStub(ctx.options.outDir);
         const moduleEntryPath = resolve(ctx.options.outDir, "module.mjs");
-        const moduleFn = await import(moduleEntryPath).then((r) => r.default || r).catch((err) => {
+        const moduleFn = await import(pathToFileURL(moduleEntryPath).toString()).then((r) => r.default || r).catch((err) => {
           consola.error(err);
           consola.error("Cannot load module. Please check dist:", moduleEntryPath);
           return null;
@@ -33,6 +36,16 @@ async function buildModule(rootDir) {
           return;
         }
         const moduleMeta = await moduleFn.getMeta();
+        if (ctx.pkg) {
+          if (!moduleMeta.name) {
+            moduleMeta.name = ctx.pkg.name;
+          }
+          if (!moduleMeta.version) {
+            moduleMeta.version = ctx.pkg.version;
+          }
+        }
+        const metaFile = resolve(ctx.options.outDir, "module.json");
+        await promises.writeFile(metaFile, JSON.stringify(moduleMeta, null, 2), "utf8");
         await writeTypes(ctx.options.outDir, moduleMeta);
       }
     }
@@ -43,18 +56,32 @@ async function writeTypes(distDir, meta) {
   if (existsSync(dtsFile)) {
     return;
   }
+  const moduleTypesFile = resolve(distDir, "module.d.ts");
+  const moduleTypes = await promises.readFile(moduleTypesFile, "utf8").catch(() => "");
+  const typeExports = findExports(moduleTypes);
+  const isStub = moduleTypes.includes("export *");
+  const hasModuleOptions = isStub || typeExports.find((exp) => exp.names.includes("ModuleOptions"));
+  const hasModuleHooks = isStub || typeExports.find((exp) => exp.names.includes("ModuleHooks"));
   const schemaShims = [];
-  if (meta.configKey) {
-    schemaShims.push(`  interface NuxtConfig { ['${meta.configKey}']?: Partial<ModuleOptions> }`, `  interface NuxtOptions { ['${meta.configKey}']?: ModuleOptions }`);
+  const moduleImports = [];
+  if (meta.configKey && hasModuleOptions) {
+    moduleImports.push("ModuleOptions");
+    schemaShims.push(`  interface NuxtConfig { ['${meta.configKey}']?: Partial<ModuleOptions> }`);
+    schemaShims.push(`  interface NuxtOptions { ['${meta.configKey}']?: ModuleOptions }`);
+  }
+  if (hasModuleHooks) {
+    moduleImports.push("ModuleHooks");
+    schemaShims.push("  interface NuxtHooks extends ModuleHooks {}");
   }
   const dtsContents = `
-import type { ModuleOptions } from './module'
+import { ${moduleImports.join(", ")} } from './module'
 
 ${schemaShims.length ? `declare module '@nuxt/schema' {
 ${schemaShims.join("\n")}
 }
 ` : ""}
-export * from './module'
+
+export { default } from './module'
 `;
   await promises.writeFile(dtsFile, dtsContents, "utf8");
 }
@@ -66,7 +93,8 @@ async function writeCJSStub(distDir) {
   const cjsStub = `module.exports = function(...args) {
   return import('./module.mjs').then(m => m.default.call(this, ...args))
 }
-module.exports.meta = require('../package.json')
+const _meta = module.exports.meta = require('./meta.json')
+module.exports.getMeta = () => Promise.resolve(_meta)
 `;
   await promises.writeFile(cjsStubFile, cjsStub, "utf8");
 }

package/dist/cli.mjs

@@ -1,14 +1,19 @@
-#!/bin/env node
+#!/usr/bin/env node
 import mri from 'mri';
 import { resolve } from 'pathe';
 import { b as buildModule } from './chunks/build.mjs';
 import 'fs';
+import 'url';
 import 'consola';
+import 'mlly';
 
 async function main() {
   const args = mri(process.argv.slice(2));
   const rootDir = resolve(args._[0] || ".");
-  await buildModule(rootDir);
+  await buildModule({
+    rootDir,
+    stub: args.stub
+  });
 }
 main().catch((err) => {
   console.error(err);

package/dist/index.d.ts

@@ -1,3 +1,7 @@
-declare function buildModule(rootDir: string): Promise<void>;
+interface BuildModuleOptions {
+    rootDir: string;
+    stub?: boolean;
+}
+declare function buildModule(opts: BuildModuleOptions): Promise<void>;
 
-export { buildModule };
+export { BuildModuleOptions, buildModule };

package/dist/index.mjs

@@ -1,4 +1,6 @@
 export { b as buildModule } from './chunks/build.mjs';
 import 'fs';
+import 'url';
 import 'pathe';
 import 'consola';
+import 'mlly';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/module-builder",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "description": "Complete solution to build Nuxt Modules",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,9 @@
     "nuxt-build-module": "./dist/cli.mjs",
     "nuxt-module-build": "./dist/cli.mjs"
   },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "unbuild",
     "example:build": "yarn nuxt-module-build ./example",
@@ -25,6 +28,7 @@
   },
   "dependencies": {
     "consola": "^2.15.3",
+    "mlly": "^0.3.19",
     "mri": "^1.2.0",
     "pathe": "^0.2.0",
     "unbuild": "^0.6.7"
@@ -32,10 +36,10 @@
   "devDependencies": {
     "@nuxt/kit": "npm:@nuxt/kit-edge@latest",
     "@nuxt/schema": "npm:@nuxt/schema-edge@latest",
-    "@nuxtjs/eslint-config-typescript": "^8.0.0",
-    "@types/mri": "^1.1.1",
-    "eslint": "^8.5.0",
+    "@nuxtjs/eslint-config-typescript": "latest",
+    "@types/mri": "latest",
+    "eslint": "latest",
     "jiti": "^1.12.9",
-    "standard-version": "^9.3.2"
+    "standard-version": "latest"
   }
 }

package/.editorconfig

@@ -1,15 +0,0 @@
-root = true
-
-[*]
-end_of_line = lf
-insert_final_newline = true
-trim_trailing_whitespace = true
-charset = utf-8
-
-[*.js]
-indent_style = space
-indent_size = 2
-
-[{package.json,*.yml,*.cjson}]
-indent_style = space
-indent_size = 2

package/.eslintignore

@@ -1,3 +0,0 @@
-dist
-.nuxt
-.output

package/.eslintrc

@@ -1,5 +0,0 @@
-{
-  "extends": [
-    "@nuxtjs/eslint-config-typescript"
-  ]
-}

package/.github/workflows/ci.yml

@@ -1,23 +0,0 @@
-name: ci
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
-        with:
-          node-version: 16
-          cache: 'yarn'
-      - run: yarn install
-      - run: yarn lint
-      - run: yarn build
-      - run: yarn example:build

package/CHANGELOG.md

@@ -1,16 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
-
-### 0.1.1 (2021-12-23)
-
-
-### Features
-
-* poc for schema types generation ([4991907](https://github.com/nuxt/module-builder/commit/49919078806b95e8d9bde64b708cb430a3bb09cf))
-
-
-### Bug Fixes
-
-* emit cjs stub before validation ([0154bc5](https://github.com/nuxt/module-builder/commit/0154bc51db2246217287c0fba4d9be42955fa306))
-* improve types generation ([68c02e6](https://github.com/nuxt/module-builder/commit/68c02e60ab4f504c6b7d078c7e8e5fb13cb81e37))

package/build.config.ts

@@ -1,9 +0,0 @@
-import { defineBuildConfig } from 'unbuild'
-
-export default defineBuildConfig({
-  declaration: true,
-  entries: [
-    './src/cli',
-    './src/index'
-  ]
-})

package/example/dist/module.cjs

@@ -1,4 +0,0 @@
-module.exports = function(...args) {
-  return import('./module.mjs').then(m => m.default.call(this, ...args))
-}
-module.exports.meta = require('../package.json')

package/example/dist/module.d.ts

@@ -1,8 +0,0 @@
-import * as _nuxt_schema from '@nuxt/schema';
-
-interface ModuleOptions {
-    apiKey: string;
-}
-declare const _default: _nuxt_schema.NuxtModule<ModuleOptions>;
-
-export { ModuleOptions, _default as default };

package/example/dist/module.mjs

@@ -1,15 +0,0 @@
-import { defineNuxtModule } from '@nuxt/kit';
-
-const module = defineNuxtModule({
-  meta: {
-    name: "my-module",
-    configKey2: "myModule"
-  },
-  defaults: {
-    apiKey: null
-  },
-  setup(_options, _nuxt) {
-  }
-});
-
-export { module as default };

package/example/dist/types.d.ts

@@ -1,9 +0,0 @@
-
-import type { ModuleOptions } from './module'
-
-declare module '@nuxt/schema' {
-  interface NuxtConfig { ['my-module']?: Partial<ModuleOptions> }
-  interface NuxtOptions { ['my-module']?: ModuleOptions }
-}
-
-export * from './module'

package/example/dist/utils.d.ts

@@ -1,3 +0,0 @@
-declare const myModuleUtils: () => void;
-
-export { myModuleUtils };

package/example/dist/utils.mjs

@@ -1,4 +0,0 @@
-const myModuleUtils = () => {
-};
-
-export { myModuleUtils };

package/example/package.json

@@ -1,32 +0,0 @@
-{
-  "name": "my-module",
-  "license": "MIT",
-  "version": "1.0.0",
-  "exports": {
-    ".": {
-      "import": "./dist/module.mjs",
-      "require": "./dist/module.cjs"
-    },
-    "./utils": "./dist/utils.mjs"
-  },
-  "main": "./dist/module.cjs",
-  "types": "./dist/types.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "prepack": "npm run build"
-  },
-  "dependencies": {
-    "@nuxt/kit": "npm:@nuxt/kit-edge@latest"
-  },
-  "devDependencies": {
-    "@nuxt/module-builder": "latest",
-    "nuxt3": "latest"
-  },
-  "build": {
-    "entries": [
-      "./src/utils"
-    ]
-  }
-}

package/renovate.json

@@ -1,11 +0,0 @@
-{
-  "extends": [
-    "@nuxtjs"
-  ],
-  "baseBranches": [
-    "main"
-  ],
-  "lockFileMaintenance": {
-    "enabled": true
-  }
-}

package/src/build.ts

@@ -1,84 +0,0 @@
-import { existsSync, promises as fsp } from 'fs'
-import { resolve } from 'pathe'
-import consola from 'consola'
-import type { ModuleMeta } from '@nuxt/schema'
-
-export async function buildModule (rootDir: string) {
-  const { build } = await import('unbuild')
-
-  await build(rootDir, false, {
-    declaration: true,
-    entries: [
-      'src/module',
-      { input: 'src/runtime/', outDir: 'dist/runtime', ext: 'mjs' }
-    ],
-    rollup: {
-      emitCJS: false,
-      cjsBridge: true
-    },
-    externals: [
-      '@nuxt/schema',
-      '@nuxt/schema-edge',
-      '@nuxt/kit',
-      '@nuxt/kit-edge'
-    ],
-    hooks: {
-      async 'rollup:done' (ctx) {
-        // Generate CommonJS stup
-        await writeCJSStub(ctx.options.outDir)
-
-        // Load module meta
-        const moduleEntryPath = resolve(ctx.options.outDir, 'module.mjs')
-        const moduleFn = await import(moduleEntryPath).then(r => r.default || r).catch((err) => {
-          consola.error(err)
-          consola.error('Cannot load module. Please check dist:', moduleEntryPath)
-          return null
-        })
-        if (!moduleFn) {
-          return
-        }
-        const moduleMeta = await moduleFn.getMeta()
-
-        // Generate types
-        await writeTypes(ctx.options.outDir, moduleMeta)
-      }
-    }
-  })
-}
-
-async function writeTypes (distDir: string, meta: ModuleMeta) {
-  const dtsFile = resolve(distDir, 'types.d.ts')
-  if (existsSync(dtsFile)) {
-    return
-  }
-
-  const schemaShims = []
-  if (meta.configKey) {
-    schemaShims.push(
-      `  interface NuxtConfig { ['${meta.configKey}']?: Partial<ModuleOptions> }`,
-      `  interface NuxtOptions { ['${meta.configKey}']?: ModuleOptions }`
-    )
-  }
-
-  const dtsContents = `
-import type { ModuleOptions } from './module'
-
-${schemaShims.length ? `declare module '@nuxt/schema' {\n${schemaShims.join('\n')}\n}\n` : ''}
-export * from './module'
-`
-
-  await fsp.writeFile(dtsFile, dtsContents, 'utf8')
-}
-
-async function writeCJSStub (distDir: string) {
-  const cjsStubFile = resolve(distDir, 'module.cjs')
-  if (existsSync(cjsStubFile)) {
-    return
-  }
-  const cjsStub = `module.exports = function(...args) {
-  return import('./module.mjs').then(m => m.default.call(this, ...args))
-}
-module.exports.meta = require('../package.json')
-`
-  await fsp.writeFile(cjsStubFile, cjsStub, 'utf8')
-}

package/src/cli.ts

@@ -1,17 +0,0 @@
-#!/bin/env node
-
-/* eslint-disable no-console */
-import mri from 'mri'
-import { resolve } from 'pathe'
-import { buildModule } from './build'
-
-async function main () {
-  const args = mri(process.argv.slice(2))
-  const rootDir = resolve(args._[0] || '.')
-  await buildModule(rootDir)
-}
-
-main().catch((err) => {
-  console.error(err)
-  process.exit(1)
-})

package/src/index.ts

@@ -1 +0,0 @@
-export * from './build'

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "Node",
-    "esModuleInterop": true,
-    "declaration": true,
-    "types": [
-      "node"
-    ]
-  },
-  "include": [
-    "src"
-  ]
-}