{"id":50967749,"url":"https://github.com/emremy/dmgapp","last_synced_at":"2026-06-18T22:30:32.120Z","repository":{"id":361735141,"uuid":"1255596318","full_name":"emremy/dmgapp","owner":"emremy","description":"Zero native dependencies, ESM-first macOS DMG generator. Create beautiful installers without node-gyp, Xcode, or compilation.","archived":false,"fork":false,"pushed_at":"2026-06-01T02:16:32.000Z","size":368,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T04:14:22.551Z","etag":null,"topics":["appdmg","apple-slici","cli","disk-image","dmg","esm","installer","m1","m2","m3","macos","nodejs","package","typescript","zero-dependencies"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emremy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T02:07:17.000Z","updated_at":"2026-06-01T02:16:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/emremy/dmgapp","commit_stats":null,"previous_names":["emremy/dmgapp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/emremy/dmgapp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emremy%2Fdmgapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emremy%2Fdmgapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emremy%2Fdmgapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emremy%2Fdmgapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emremy","download_url":"https://codeload.github.com/emremy/dmgapp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emremy%2Fdmgapp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34510281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appdmg","apple-slici","cli","disk-image","dmg","esm","installer","m1","m2","m3","macos","nodejs","package","typescript","zero-dependencies"],"created_at":"2026-06-18T22:30:27.899Z","updated_at":"2026-06-18T22:30:32.103Z","avatar_url":"https://github.com/emremy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎯 dmgapp\n\n**The modern way to create macOS DMG installers**\n\n\u003e Zero dependencies. Zero compilation. Zero headaches.\n\nCreate beautiful, professional macOS DMG installers in seconds. Works everywhere Node.js works - including Apple Silicon.\n\n## ✨ Why dmgapp?\n\n### 🚀 **Just Works™**\n```bash\nnpm install -g dmgapp\ndmgapp config.json MyApp.dmg\n```\nThat's it. No Xcode. No Python. No `node-gyp` errors. No compilation failures.\n\n### 💎 **Production Ready**\n- **Zero runtime dependencies** - Pure Node.js, nothing to break\n- **Apple Silicon native** - M1/M2/M3 support out of the box\n- **CI/CD friendly** - Works in GitHub Actions, GitLab CI, anywhere\n- **Battle-tested** - Handles spaces in paths, hidden files, retina displays\n\n### ⚡ **Lightning Fast**\nNo compilation step means instant installation and faster builds.\n\n## 📦 Installation\n\n```bash\n# Global installation\nnpm install -g dmgapp\n\n# Or as a dev dependency\nnpm install --save-dev dmgapp\n```\n\n**Requirements:** Node.js 18+ and macOS\n\n## 🎨 Quick Start\n\n### 1. Create `config.json`\n\n```json\n{\n  \"title\": \"My Awesome App\",\n  \"icon\": \"icon.icns\",\n  \"background\": \"background.png\",\n  \"icon-size\": 128,\n  \"window\": {\n    \"size\": { \"width\": 640, \"height\": 480 }\n  },\n  \"contents\": [\n    { \"x\": 448, \"y\": 344, \"type\": \"link\", \"path\": \"/Applications\" },\n    { \"x\": 192, \"y\": 344, \"type\": \"file\", \"path\": \"MyApp.app\" }\n  ]\n}\n```\n\n### 2. Generate your DMG\n\n```bash\ndmgapp config.json MyApp.dmg\n```\n\n### 3. Done! 🎉\n\nYour professional DMG installer is ready at `MyApp.dmg`.\n\n## 📖 Configuration\n\n### Minimal Example\n\nJust the essentials:\n\n```json\n{\n  \"title\": \"My App\",\n  \"contents\": [\n    { \"x\": 448, \"y\": 344, \"type\": \"link\", \"path\": \"/Applications\" },\n    { \"x\": 192, \"y\": 344, \"type\": \"file\", \"path\": \"MyApp.app\" }\n  ]\n}\n```\n\n### Full Example\n\nAll the bells and whistles:\n\n```json\n{\n  \"title\": \"My Application\",\n  \"icon\": \"volume-icon.icns\",\n  \"background\": \"background.png\",\n  \"background-color\": \"#ffffff\",\n  \"icon-size\": 128,\n  \"window\": {\n    \"position\": { \"x\": 100, \"y\": 100 },\n    \"size\": { \"width\": 640, \"height\": 480 }\n  },\n  \"format\": \"UDZO\",\n  \"filesystem\": \"HFS+\",\n  \"contents\": [\n    { \"x\": 448, \"y\": 344, \"type\": \"link\", \"path\": \"/Applications\" },\n    { \"x\": 192, \"y\": 344, \"type\": \"file\", \"path\": \"MyApp.app\" }\n  ],\n  \"code-sign\": {\n    \"signing-identity\": \"Developer ID Application: My Company (ABC123)\",\n    \"identifier\": \"com.mycompany.myapp\"\n  }\n}\n```\n\n### Configuration Options\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `title` | string | ✅ | Volume name shown when mounted |\n| `contents` | array | ✅ | Files and links to include |\n| `icon` | string | | Volume icon (`.icns` file) |\n| `background` | string | | Background image |\n| `background-color` | string | | Background color (CSS format) |\n| `icon-size` | number | | Icon size in pixels (default: 80) |\n| `window` | object | | Window configuration |\n| `format` | string | | DMG format (default: `UDZO`) |\n| `filesystem` | string | | `HFS+` or `APFS` |\n| `code-sign` | object | | Code signing options |\n\n### Content Items\n\nEach item in `contents`:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `x` | number | ✅ | X position |\n| `y` | number | ✅ | Y position |\n| `type` | string | ✅ | `file`, `link`, or `position` |\n| `path` | string | ✅ | Path to file or link target |\n| `name` | string | | Custom display name |\n\n**Content Types:**\n- `file` - Copy a file or folder into the DMG\n- `link` - Create a symlink (e.g., to `/Applications`)\n- `position` - Position an existing file (for hidden files)\n\n### DMG Formats\n\n| Format | Description |\n|--------|-------------|\n| `UDZO` | zlib-compressed (recommended) |\n| `UDBZ` | bzip2-compressed |\n| `ULFO` | lzfse-compressed (macOS 10.11+) |\n| `ULMO` | lzma-compressed (macOS 10.15+) |\n| `UDRW` | Read/write (for development) |\n| `UDRO` | Read-only |\n| `UDCO` | ADC-compressed |\n\n## 💻 Programmatic API\n\nUse dmgapp in your build scripts:\n\n```javascript\nimport { generateDMG } from 'dmgapp';\n\nconst generator = generateDMG({\n  source: './config.json',\n  target: './output.dmg'\n});\n\ngenerator.on('progress', (info) =\u003e {\n  console.log(`[${info.current}/${info.total}] ${info.title}`);\n});\n\ngenerator.on('finish', () =\u003e {\n  console.log('✅ DMG created successfully!');\n});\n\ngenerator.on('error', (err) =\u003e {\n  console.error('❌ Error:', err);\n});\n\nawait generator.generate();\n```\n\n### Inline Configuration\n\nSkip the JSON file and configure directly:\n\n```javascript\nimport { generateDMG } from 'dmgapp';\n\nconst generator = generateDMG({\n  target: './output.dmg',\n  basepath: process.cwd(),\n  specification: {\n    title: 'My App',\n    contents: [\n      { x: 448, y: 344, type: 'link', path: '/Applications' },\n      { x: 192, y: 344, type: 'file', path: 'MyApp.app' }\n    ]\n  }\n});\n\nawait generator.generate();\n```\n\n## 🖼️ Retina Backgrounds\n\ndmgapp automatically creates retina-ready backgrounds:\n\n```\nbackground.png      ← Standard resolution\nbackground@2x.png   ← Retina resolution (2x)\n```\n\nWhen both files exist, dmgapp combines them into a single `.tiff` file that macOS displays correctly on all screens.\n\n**Pro tip:** Use the same filename with `@2x` before the extension.\n\n## 🛠️ CLI Reference\n\n```bash\ndmgapp \u003cconfig.json\u003e \u003coutput.dmg\u003e [options]\n```\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `-V, --version` | Show version number |\n| `-h, --help` | Show help message |\n| `-q, --quiet` | Suppress progress output |\n| `-v, --verbose` | Show detailed error messages |\n\n### Examples\n\n```bash\n# Basic usage\ndmgapp config.json MyApp.dmg\n\n# Quiet mode (for CI/CD)\ndmgapp config.json MyApp.dmg --quiet\n\n# Debug mode\ndmgapp config.json MyApp.dmg --verbose\n```\n\n## 🔄 Migration from node-appdmg\n\n**Good news:** dmgapp is a drop-in replacement. Your existing configs work without changes.\n\n```bash\n# Before\nappdmg config.json output.dmg\n\n# After\ndmgapp config.json output.dmg\n```\n\n### Why Switch?\n\n| Feature | node-appdmg | dmgapp |\n|---------|-------------|--------|\n| Installation | ❌ Requires Xcode, Python | ✅ Just `npm install` |\n| Apple Silicon | ❌ Broken | ✅ Full support |\n| Node.js 20+ | ❌ Fails | ✅ Works perfectly |\n| CI/CD setup | ❌ Complex | ✅ Zero config |\n| Dependencies | ❌ Native C++ bindings | ✅ Zero runtime deps |\n\n## 🤔 Troubleshooting\n\n### \"Resource busy\" errors\n\n**Problem:** DMG won't unmount.\n\n**Solution:** Close any Finder windows showing the mounted volume. dmgapp automatically retries with exponential backoff.\n\n### Code signing fails\n\n**Problem:** `codesign` reports invalid identity.\n\n**Solution:** List your signing identities:\n```bash\nsecurity find-identity -v -p codesigning\n```\n\nUse the exact identity string from the output.\n\n### Background not showing\n\n**Problem:** DMG opens with white background.\n\n**Solutions:**\n- Use paths relative to the JSON file\n- Supported formats: PNG, JPG, TIFF\n- For retina: ensure `@2x` file exists in same directory\n\n### Paths with spaces\n\n**Problem:** App name contains spaces (e.g., \"My App.app\").\n\n**Solution:** Just use the path normally - dmgapp handles spaces correctly:\n```json\n{ \"path\": \"My App.app\" }\n```\n\n## 🚀 CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Build DMG\non: [push]\n\njobs:\n  build:\n    runs-on: macos-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n      \n      - name: Install dmgapp\n        run: npm install -g dmgapp\n      \n      - name: Build DMG\n        run: dmgapp config.json MyApp.dmg --quiet\n      \n      - name: Upload artifact\n        uses: actions/upload-artifact@v4\n        with:\n          name: installer\n          path: MyApp.dmg\n```\n\n### GitLab CI\n\n```yaml\nbuild-dmg:\n  stage: package\n  tags:\n    - macos\n  script:\n    - npm install -g dmgapp\n    - dmgapp config.json MyApp.dmg --quiet\n  artifacts:\n    paths:\n      - MyApp.dmg\n```\n\n## 📊 Requirements\n\n- **macOS** (darwin platform)\n- **Node.js 18** or higher\n- **No build tools required** ✨\n\n## 🎯 Comparison\n\n### vs node-appdmg\n\n| Aspect | node-appdmg | dmgapp |\n|--------|-------------|--------|\n| **Dependencies** | Native C++ bindings | Zero runtime deps |\n| **Installation** | Requires Xcode + Python | `npm install` |\n| **Apple Silicon** | Broken | Full support |\n| **Node.js 20+** | Fails | Works |\n| **Code size** | ~800 lines JS | ~1,200 lines TS |\n| **Type safety** | None | Full TypeScript |\n| **Module system** | CommonJS | ESM |\n\n### vs dmgbuild (Python)\n\n| Aspect | dmgbuild | dmgapp |\n|--------|----------|--------|\n| **Language** | Python | JavaScript/TypeScript |\n| **Runtime** | Python 3 | Node.js 18+ |\n| **Dependencies** | Multiple Python packages | Zero runtime deps |\n| **Installation** | `pip install` | `npm install` |\n| **Config format** | Python script | JSON |\n\n## 🤝 Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests: `npm test`\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\nBuilt as a modern replacement for [node-appdmg](https://github.com/LinusU/node-appdmg) by Linus Unnebäck [@LinusU](https://github.com/LinusU)\n---\n\n**Made with ❤️ for the macOS developer community**\n\n[Report an issue](https://github.com/emremy/dmgapp/issues) • [View source](https://github.com/emremy/dmgapp)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femremy%2Fdmgapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femremy%2Fdmgapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femremy%2Fdmgapp/lists"}