{"id":14186,"library":"umd","title":"UMD Universal Module Definition Wrapper","description":"The `umd` package, currently at version 3.0.3, provides a specialized utility for wrapping JavaScript modules with Universal Module Definition (UMD) boilerplate. It is primarily designed for integration into automated build systems, enabling developers to convert their proprietary or standard modules into a format compatible with a wide array of JavaScript environments, including Asynchronous Module Definition (AMD) loaders, CommonJS environments (like Node.js), and traditional browser global script tags. The library supports two primary input formats: a 'return style' module, where the module's export is the direct result of a `return` statement, and CommonJS-style modules which require an explicit `commonJS: true` option. A key differentiator is its synchronous operation and its focus on preventing naming conflicts between multiple UMD modules on the same page. The package offers functions to generate the UMD prelude, postlude, or to wrap an entire module source string. While UMD was crucial for cross-environment compatibility, its necessity has somewhat diminished with the widespread adoption of native ECMAScript Modules (ESM) in modern environments.","status":"maintenance","version":"3.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/ForbesLindesay/umd","tags":["javascript"],"install":[{"cmd":"npm install umd","lang":"bash","label":"npm"},{"cmd":"yarn add umd","lang":"bash","label":"yarn"},{"cmd":"pnpm add umd","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `umd` function is part of the module's default export. It is predominantly used in Node.js build scripts, which typically use CommonJS `require`.","wrong":"import umd from 'umd';","symbol":"umd","correct":"const umd = require('umd');"},{"note":"Accesses the `prelude` utility function to get the opening UMD boilerplate for a module. Available via the default CommonJS export.","symbol":"umd.prelude","correct":"const umd = require('umd'); const prelude = umd.prelude('my-module-name');"},{"note":"Accesses the `postlude` utility function to get the closing UMD boilerplate for a module. Available via the default CommonJS export.","symbol":"umd.postlude","correct":"const umd = require('umd'); const postlude = umd.postlude('my-module-name');"}],"quickstart":{"code":"const umd = require('umd');\nconst fs = require('fs');\n\n// Example 1: 'return' style module (default behavior)\nconst myModuleSource = `\nfunction greeter(name) {\n  return 'Hello, ' + name;\n}\ngreeter.version = '1.0.0';\nreturn greeter;\n`;\n\nconst umdOutput = umd('my-greeter', myModuleSource);\nconsole.log('// UMD wrapped \"return style\" module:');\nconsole.log(umdOutput);\nfs.writeFileSync('my-greeter.umd.js', umdOutput);\n\n// Example 2: CommonJS style module (requires commonJS option)\nconst myCommonJSModuleSource = `\nexports.add = (a, b) => a + b;\nexports.subtract = (a, b) => a - b;\n`;\n\nconst umdCJSOutput = umd('my-math-lib', myCommonJSModuleSource, { commonJS: true });\nconsole.log('\\n// UMD wrapped \"CommonJS style\" module:');\nconsole.log(umdCJSOutput);\nfs.writeFileSync('my-math-lib.umd.js', umdCJSOutput);\n\nconsole.log('\\nUMD modules generated: my-greeter.umd.js and my-math-lib.umd.js');","lang":"javascript","description":"Demonstrates how to use the `umd` package programmatically to wrap both 'return style' and CommonJS modules, outputting the result to files and console. Requires Node.js to run."},"warnings":[{"fix":"For CommonJS source, use `umd(name, source, { commonJS: true })`. For 'return style', ensure your code concludes with `return yourExportedValue;`.","message":"By default, `umd` expects module source code to `return` the module's export. If your source uses CommonJS `module.exports` or `exports.propertyName`, you must explicitly set the `commonJS: true` option.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure module names adhere to `/[a-zA-Z0-9$_]+/` patterns, typically camelCase (e.g., `myAwesomeModule`), to avoid unintended transformations.","message":"Module names passed to `umd` have strict character requirements (alphanumeric, $, _, not starting with a number). Invalid characters will be silently stripped or converted to camel case, potentially leading to unexpected global variable names.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consider if ESM or modern bundlers are more appropriate for your module distribution, especially for new projects or targeting modern environments. Use UMD primarily for legacy support.","message":"UMD is a legacy module format. While it provides broad compatibility, its relevance has decreased with the widespread adoption of native ECMAScript Modules (ESM) in modern browsers and Node.js. Using UMD might introduce unnecessary boilerplate or complexity if your target environments are primarily ESM-compatible.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'3.0.3':12 'adopt':166 'amd':61 'array':53 'asynchron':58 'autom':34 'boilerpl':26 'browser':69 'build':35 'commonj':63,99,106 'commonjs-styl':98 'compat':49,157 'conflict':122 'convert':40 'cross':155 'cross-environ':154 'crucial':152 'current':9 'definit':4,24,60 'design':30 'develop':38 'differenti':111 'diminish':162 'direct':91 'ecmascript':169 'enabl':37 'entir':145 'environ':56,64,156,174 'esm':171 'explicit':105 'export':88 'focus':118 'format':48,79 'function':134 'generat':136 'global':70 'includ':57 'input':78 'integr':32 'javascript':19,55,175 'key':110 'librari':74 'like':65 'loader':62 'modern':173 'modul':3,20,23,45,59,83,86,101,126,146,170 'multipl':124 'name':121 'nativ':168 'necess':159 'node.js':66 'offer':133 'oper':115 'option':108 'packag':8,132 'page':130 'postlud':140 'prelud':139 'prevent':120 'primari':77 'primarili':29 'proprietari':42 'provid':13 'requir':103 'result':92 'return':81,95 'script':71 'somewhat':161 'sourc':147 'special':15 'standard':44 'statement':96 'string':148 'style':82,100 'support':75 'synchron':114 'system':36 'tag':72 'tradit':68 'true':107 'two':76 'umd':1,7,25,125,138,150 'univers':2,22 'util':16 'version':11 'wide':52 'widespread':165 'wrap':18,143 'wrapper':5","created_at":"2026-04-20T01:58:23.031477+00:00","updated_at":"2026-04-20T01:58:23.031477+00:00","problems":[{"fix":"Ensure that for CommonJS-style source, the `commonJS` option is set: `umd('your-module', yourCjsSource, { commonJS: true });`","cause":"Attempted to wrap a CommonJS module's source code without setting the `commonJS: true` option in the `umd()` function call.","error":"ReferenceError: module is not defined (or exports is not defined)"},{"fix":"Modify your module source to explicitly `return` the value you wish to export, for example: `function MyFunc() {...} return MyFunc;`","cause":"The source code for a 'return style' module (the default `umd` expectation) does not conclude with a `return` statement exporting the desired value.","error":"Wrapped UMD module does not export anything useful (e.g., module variable is undefined in consuming environments)"},{"fix":"Be aware of the automatic camelCasing and character stripping. If you need a specific global name, ensure your input `name` parameter adheres to JavaScript variable naming conventions (e.g., 'myCoolModule' instead of 'my-cool-module') or inspect the generated UMD output to confirm the exact name.","cause":"The `umd` package automatically converts the provided module `name` to camelCase and strips invalid characters to create a valid global variable name for the UMD wrapper.","error":"UMD global variable name differs from expected module name (e.g., `my-cool-module` becomes `myCoolModule`)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/ForbesLindesay/umd","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/umd","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}