@nuxt/module-builder 0.0.0 → 0.1.1

package/.github/workflows/ci.yml

@@ -20,4 +20,4 @@ jobs:
       - run: yarn install
       - run: yarn lint
       - run: yarn build
-      - run: yarn play
+      - run: yarn example:build

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 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/README.md

@@ -1,18 +1,97 @@
-# Nuxt Module Builder
+# 📦 Nuxt Module Builder
 
-> Build Nuxt modules using [unjs/unbuild](https://github.com/unjs/unbuild).
+> Complete solution to build Nuxt Modules.
 
-## Usage
+**🧪 This tool is still under heavy development for Nuxt3. Feedback is more than welcome!**
 
-- Install `@nuxt/module-builder` as a devDependency
-- Use `npx nuxt-build-module` to build module
+## Features
 
-Note: Module structure needs `src/module.ts` and optional `src/runtime/`
+- Unified build with [unjs/unbuild](https://github.com/unjs/unbuild)
+- Compatible with Nuxt 3 and Nuxt Kit
+- Automated build config using last module spec
+- Typescript and ESM support
+- Auto generated CommonJS stubs
+- Auto generated types and shims for `@nuxt/schema`
 
-## Development
 
-- Clone this repository
-- Try changes using `yarn play` (it will build `playground/` to `playground/dist/`)
+## Project structure
+
+Using module builder, requires a special project setup. You can check a full example [here](./example).
+
+### `src/module.ts`
+
+This is the entrypoint for module definition.
+
+A default export using `defineNuxtModule` and `ModuleOptions` type export is expected.
+
+```js [src/module.ts]
+import { defineNuxtModule } from '@nuxt/kit'
+
+export interface ModuleOptions {
+  apiKey: string
+}
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'my-module',
+    configKey: 'myModule'
+  },
+  defaults: {
+    apiKey: 'test'
+  },
+  async setup (moduleOptions, nuxt) {
+    // Write module logic in setup function
+  }
+})
+```
+
+### `src/runtime/`
+
+Any runtime file and code that we need to provide by module including plugins, composables and server api, should be in this directory.
+
+Each file will be transformed individually using [unjs/mkdist](https://github.com/unjs/mkdist) to `dist/runtime/`.
+
+<!-- TODO: Docs about how to address runtime from within setup -->
+
+### `package.json`:
+
+A minimum `package.json` should look like this:
+
+```json [package.json]
+{
+  "name": "my-module",
+  "license": "MIT",
+  "version": "1.0.0",
+  "exports": {
+    ".": {
+      "import": "./dist/module.mjs",
+      "require": "./dist/module.cjs"
+    }
+  },
+  "main": "./dist/module.cjs",
+  "types": "./dist/types.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build"
+  },
+  "dependencies": {
+    "@nuxt/kit": "npm:@nuxt/kit-edge@latest"
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "latest"
+  }
+}
+```
+
+
+## 💻 Development
+
+- Clone repository
+- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable` (use `npm i -g corepack` for Node.js < 16.10)
+- Install dependencies using `yarn install`
+- Try building [example module](./example) using `yarn example:build`
 
 ## License
 

package/build.config.ts

@@ -2,9 +2,6 @@ import { defineBuildConfig } from 'unbuild'
 
 export default defineBuildConfig({
   declaration: true,
-  rollup: {
-    emitCJS: false
-  },
   entries: [
     './src/cli',
     './src/index'

package/dist/chunks/build.mjs

@@ -1,5 +1,6 @@
-import { promises } from 'fs';
+import { existsSync, promises } from 'fs';
 import { resolve } from 'pathe';
+import consola from 'consola';
 
 async function buildModule(rootDir) {
   const { build } = await import('unbuild');
@@ -20,16 +21,49 @@ async function buildModule(rootDir) {
       "@nuxt/kit-edge"
     ],
     hooks: {
-      async "build:done"(ctx) {
+      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) => {
+          consola.error(err);
+          consola.error("Cannot load module. Please check dist:", moduleEntryPath);
+          return null;
+        });
+        if (!moduleFn) {
+          return;
+        }
+        const moduleMeta = await moduleFn.getMeta();
+        await writeTypes(ctx.options.outDir, moduleMeta);
       }
     }
   });
 }
+async function writeTypes(distDir, meta) {
+  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' {
+${schemaShims.join("\n")}
+}
+` : ""}
+export * from './module'
+`;
+  await promises.writeFile(dtsFile, dtsContents, "utf8");
+}
 async function writeCJSStub(distDir) {
   const cjsStubFile = resolve(distDir, "module.cjs");
-  const cjsStub = `// CommonJS proxy to use native ESM
-module.exports = function(...args) {
+  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')

package/dist/cli.mjs

@@ -3,6 +3,7 @@ import mri from 'mri';
 import { resolve } from 'pathe';
 import { b as buildModule } from './chunks/build.mjs';
 import 'fs';
+import 'consola';
 
 async function main() {
   const args = mri(process.argv.slice(2));

package/dist/index.mjs

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

package/example/dist/module.cjs

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,9 @@
+
+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

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

package/example/dist/utils.mjs

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

package/example/package.json

@@ -0,0 +1,32 @@
+{
+  "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/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@nuxt/module-builder",
-  "version": "0.0.0",
+  "version": "0.1.1",
+  "description": "Complete solution to build Nuxt Modules",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -10,27 +11,30 @@
   },
   "types": "./dist/index.d.ts",
   "bin": {
-    "nuxt-build-module": "./dist/cli.mjs"
+    "nuxt-build-module": "./dist/cli.mjs",
+    "nuxt-module-build": "./dist/cli.mjs"
   },
   "scripts": {
     "build": "unbuild",
-    "cli": "jiti ./src/cli.ts",
+    "example:build": "yarn nuxt-module-build ./example",
     "lint": "eslint --ext .ts,.js,.mjs .",
+    "nuxt-module-build": "jiti ./src/cli.ts",
     "prepack": "yarn build",
-    "play": "yarn cli ./playground",
     "release": "yarn test && standard-version && git push --follow-tags && npm publish",
     "test": "yarn lint"
   },
   "dependencies": {
+    "consola": "^2.15.3",
     "mri": "^1.2.0",
     "pathe": "^0.2.0",
-    "unbuild": "^0.6.2"
+    "unbuild": "^0.6.7"
   },
   "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.3.0",
+    "eslint": "^8.5.0",
     "jiti": "^1.12.9",
     "standard-version": "^9.3.2"
   }

package/src/build.ts

@@ -1,5 +1,7 @@
-import { promises as fsp } from 'fs'
+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')
@@ -21,17 +23,59 @@ export async function buildModule (rootDir: string) {
       '@nuxt/kit-edge'
     ],
     hooks: {
-      async 'build:done' (ctx) {
+      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')
-  const cjsStub = `// CommonJS proxy to use native ESM
-module.exports = function(...args) {
+  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')

package/playground/package.json

@@ -1,17 +0,0 @@
-{
-  "private": true,
-  "name": "mymodule",
-  "main": "./dist/module.cjs",
-  "types": "./dist/module.d.ts",
-  "build": {
-    "entries": [
-      "./src/custom"
-    ]
-  },
-  "exports": {
-    ".": {
-      "require": "./dist/module.cjs",
-      "import": "./dist/module.mjs"
-    }
-  }
-}

package/playground/src/custom.ts

@@ -1 +0,0 @@
-// Custom entry

package/playground/src/module.ts

@@ -1,5 +0,0 @@
-import { defineNuxtModule } from '@nuxt/kit'
-
-export default defineNuxtModule({
-  setup () {}
-})

package/playground/src/runtime/plugin.ts

@@ -1,4 +0,0 @@
-// @ts-ignore
-import { defineNuxtPlugin } from '#app'
-
-export default defineNuxtPlugin((_nuxtApp) => {})