docs: add examples (#334)

Co-authored-by: Pooya Parsa <[email protected]>

Author: Barbapapazes

examples/1.zero-config/README.md

@@ -0,0 +1,7 @@
+# Unbuild zero config example
+
+Unbuild automatically infers the build configuration from `exports` field in [`package.json`](./package.json).
+
+Since 3 `types`, `import` and `require` fields are set, build automatically includes them.
+
+Unbuild also supports building multiple entries.

examples/1.zero-config/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "unbuild-example-zero-config",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./utils": {
+      "import": {
+        "types": "./dist/utils.d.mts",
+        "default": "./dist/utils.mjs"
+      },
+      "require": {
+        "types": "./dist/utils.d.cts",
+        "default": "./dist/utils.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "build:stub": "unbuild --stub"
+  },
+  "devDependencies": {
+    "unbuild": "^2.0.0"
+  }
+}

examples/1.zero-config/src/index.ts

@@ -0,0 +1,3 @@
+export function main(data: string): string {
+  return `Hello ${data}!`;
+}

examples/1.zero-config/src/utils.ts

@@ -0,0 +1,3 @@
+export default function sum(a: number, b: number) {
+  return a + b;
+}

examples/2.mkdist/README.md

@@ -0,0 +1,3 @@
+# Unbuild mkdist example
+
+A simple example of how to generate ESM, CJS and DTS from TypeScript using a folder as entry point.

examples/2.mkdist/build.config.ts

@@ -0,0 +1,23 @@
+import { defineBuildConfig } from "unbuild";
+
+export default defineBuildConfig({
+  entries: [
+    "src/index.ts",
+    {
+      input: "src/plugins/",
+      outDir: "dist/plugins/",
+      format: "esm",
+    },
+    {
+      input: "src/plugins/",
+      outDir: "dist/plugins/",
+      format: "cjs",
+      ext: "cjs",
+      declaration: false,
+    },
+  ],
+  declaration: true,
+  rollup: {
+    emitCJS: true,
+  },
+});

examples/2.mkdist/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "unbuild-example-mkdist",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./plugins/*": {
+      "import": {
+        "types": "./dist/plugins/*.d.mts",
+        "default": "./dist/plugins/*.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/*.d.cts",
+        "default": "./dist/plugins/*.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "build:stub": "unbuild --stub"
+  },
+  "devDependencies": {
+    "unbuild": "^2.0.0"
+  }
+}

examples/2.mkdist/src/index.ts

@@ -0,0 +1,3 @@
+export function main(data: string): string {
+  return `Hello ${data}!`;
+}

examples/2.mkdist/src/plugins/vite.ts

@@ -0,0 +1,3 @@
+export default function vitePlugin(): string {
+  return "Hello Vite!";
+}

examples/2.mkdist/src/plugins/webpack.ts

@@ -0,0 +1,3 @@
+export default function webpackPlugin(): string {
+  return "Hello Webpack!";
+}

examples/3.untyped/.gitignore

@@ -0,0 +1 @@
+schema

examples/3.untyped/README.md

@@ -0,0 +1 @@
+# Unbuild untyped example

examples/3.untyped/build.config.ts

@@ -0,0 +1,17 @@
+import { defineBuildConfig } from "unbuild";
+
+export default defineBuildConfig({
+  entries: [
+    "src/index.ts",
+    {
+      builder: "untyped",
+      input: "src/index.ts",
+      outDir: "schema",
+      name: "schema",
+    },
+  ],
+  declaration: true,
+  rollup: {
+    emitCJS: true,
+  },
+});

examples/3.untyped/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "unbuild-example-untyped",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild"
+  },
+  "devDependencies": {
+    "unbuild": "^2.0.0"
+  }
+}

examples/3.untyped/src/index.ts

@@ -0,0 +1,25 @@
+export function sendMessage(
+  message: string,
+  date = new Date(),
+  flash?: boolean,
+): string {
+  return "OK";
+}
+
+export const config = {
+  name: "default",
+  price: 12.5,
+  /**
+   * checked state
+   */
+  checked: false,
+  dimensions: {
+    /** width in px */
+    width: 10,
+    /** height in px */
+    height: 10,
+  },
+  tags: {
+    $resolve: (val?: string[]) => ["tag1", ...(val || [])].filter(Boolean),
+  },
+};

examples/README.md

@@ -0,0 +1,7 @@
+# unbuild examples
+
+In this directory you can find some examples of how to use unbuild.
+
+- [Zero Config](./1.zero-config/)
+- [mkdist](./2.mkdist/)
+- [untyped](./3.untyped/)

package.json

@@ -19,8 +19,8 @@
   "scripts": {
     "build": "pnpm unbuild",
     "dev": "pnpm unbuild test/fixture",
-    "lint": "eslint . && prettier -c src test",
-    "lint:fix": "eslint --fix . && prettier -w src test",
+    "lint": "eslint . && prettier -c src test examples",
+    "lint:fix": "eslint --fix . && prettier -w src test examples",
     "prepack": "pnpm unbuild",
     "release": "pnpm test && changelogen --release && git push --follow-tags && npm publish",
     "prerelease": "pnpm test && changelogen --prerelease --release && git push --follow-tags && npm publish --tag rc",
@@ -63,7 +63,8 @@
     "eslint-config-unjs": "^0.3.2",
     "prettier": "^3.3.0",
     "typescript": "^5.4.5",
-    "vitest": "^1.6.0"
+    "vitest": "^1.6.0",
+    "unbuild": "workspace:."
   },
   "peerDependencies": {
     "typescript": "^5.4.5"