# appdmg

> Generate beautiful DMG-images for your OS X applications.

Latest version **0.6.6** (published 2023-02-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install appdmg
pnpm add appdmg
yarn add appdmg
bun add appdmg
```

Provides the command `appdmg`.

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.6.6 |
| Published | 2023-02-03 |
| First published | 2013-11-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/appdmg) |
| Module format | CommonJS |
| Node | >=8.5 |
| Dependencies | 11 |
| Unpacked size | 1.7 MB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1746 |
| Author | Linus Unnebäck |
| Maintainers | linusu, cstruct |

## Links

- npm: https://www.npmjs.com/package/appdmg
- Repository: https://github.com/LinusU/node-appdmg
- Homepage: https://github.com/LinusU/node-appdmg#readme
- Issues: https://github.com/LinusU/node-appdmg/issues
- npm.io page: https://npm.io/package/appdmg

## Dependencies (11)

- [async](https://npm.io/package/async.md) ^1.4.2
- [execa](https://npm.io/package/execa.md) ^1.0.0
- [fs-temp](https://npm.io/package/fs-temp.md) ^1.0.0
- [ds-store](https://npm.io/package/ds-store.md) ^0.1.5
- [fs-xattr](https://npm.io/package/fs-xattr.md) ^0.3.0
- [minimist](https://npm.io/package/minimist.md) ^1.1.3
- [image-size](https://npm.io/package/image-size.md) ^0.7.4
- [parse-color](https://npm.io/package/parse-color.md) ^1.0.0
- [path-exists](https://npm.io/package/path-exists.md) ^4.0.0
- [repeat-string](https://npm.io/package/repeat-string.md) ^1.5.4
- [is-my-json-valid](https://npm.io/package/is-my-json-valid.md) ^2.20.0

## Recent versions

- 0.6.6 (latest) — 2023-02-03
- 0.6.5 — 2023-02-01
- 0.6.4 — 2022-03-17
- 0.6.3 — 2022-03-17
- 0.6.2 — 2021-07-23
- 0.6.1 — 2021-07-07
- 0.6.0 — 2019-05-28
- 0.5.2 — 2017-11-12
- 0.5.1 — 2017-10-22
- 0.5.0 — 2017-10-22
- 0.4.5 — 2016-05-22
- 0.4.4 — 2016-05-22
- 0.4.3 — 2016-05-17
- 0.4.2 — 2016-05-15
- 0.4.1 — 2016-05-15
- … 30 more at https://npm.io/package/appdmg/versions

## README

# node-appdmg

Generate beautiful DMG-images for your OS X applications.

## Installation

```sh
npm install -g appdmg
```

## Usage

```sh
appdmg <json-path> <dmg-path>
```

- `json-path`: Path to the JSON Specification file
- `dmg-path`:  Path at which to place the final DMG

## Test

To produce a test DMG to your desktop, run the following command:

```sh
appdmg test/assets/appdmg.json ~/Desktop/test.dmg
```

## JSON Input

![Visualization](/help/help.png?raw=true)

The JSON input for the image follows a simple structure. All paths are relative to
the JSON file's path.

### Example

```json
{
  "title": "Test Application",
  "icon": "test-app.icns",
  "background": "test-background.png",
  "contents": [
    { "x": 448, "y": 344, "type": "link", "path": "/Applications" },
    { "x": 192, "y": 344, "type": "file", "path": "TestApp.app" }
  ]
}
```

### Specification

- `title` (string, required) - The title of the produced DMG, which will be shown when mounted
- `icon` (string, optional) - Path to your icon, which will be shown when mounted
- `background` (string, optional) - Path to your background
- `background-color` (string, optional) - Background color (accepts css colors)
- `icon-size` (number, optional) - Size of all the icons inside the DMG
- `window` (object, optional) - Window options
  - `position` (object, optional) - Position when opened
    - `x` (number, required) - X position relative to left of the screen
    - `y` (number, required) - Y position relative to bottom of the screen
  - `size` (object, optional) - Window size
    - `width` (number, required) - Window width
    - `height` (number, required) - Window height
- `format` (enum[string], optional) - Disk image format
    - `UDRW` - UDIF read/write image
    - `UDRO` - UDIF read-only image
    - `UDCO` - UDIF ADC-compressed image
    - `UDZO` - UDIF zlib-compressed image
    - `UDBZ` - UDIF bzip2-compressed image (OS X 10.4+ only)
    - `ULFO` - UDIF lzfse-compressed image (OS X 10.11+ only)
    - `ULMO` - UDIF lzma-compressed image (macOS 10.15+ only)
- `filesystem` (enum[string], optional) - Disk image filesystem
    - `HFS+`
    - `APFS` (macOS 10.13+ only)
- `contents` (array[object], required) - This is the contents of your DMG.
    - `x` (number, required) - X position relative to icon center
    - `y` (number, required) - Y position relative to icon center
    - `type` (enum[string], required)
      - `link` - Creates a link to the specified target
      - `file` - Adds a file to the DMG
      - `position` - Positions a present file
    - `path` (string, required) - Path to the file
    - `name` (string, optional) - Name of the file within the DMG
- `code-sign` (object, optional) - Options for codesigning the DMG
  - `signing-identity` (string, required) - The identity with which to sign the resulting DMG
  - `identifier` (string, optional) - Explicitly set the unique identifier string that is embedded in code signatures

`0.1.x` used a different JSON format. This format is still supported but
deprecated, please update your json.

### Retina background

Finder can display retina backgrounds if packaged correctly into a `.tiff`
file. `appdmg` will do this for you automatically if it can find a file
with the same name as the background appended with `@2x`.

E.g. if the json contains `"background": "TestBkg.png"` then add a file
with the name `TestBkg@2x.png` into the same folder.

## API

The application can also be called from within
another javascript file, example:

```javascript

const appdmg = require('appdmg');
const ee = appdmg({ source: 'test/appdmg.json', target: 'test.dmg' });

ee.on('progress', function (info) {

  // info.current is the current step
  // info.total is the total number of steps
  // info.type is on of 'step-begin', 'step-end'

  // 'step-begin'
  // info.title is the title of the current step

  // 'step-end'
  // info.status is one of 'ok', 'skip', 'fail'

});

ee.on('finish', function () {
  // There now is a `test.dmg` file
});

ee.on('error', function (err) {
  // An error occurred
});

```

You can also pass in the specification directly instead of reading it from a file. `basepath` should be a path which will be used to resolve other paths in the specification.

```javascript
const ee = appdmg({
  target: 'test.dmg',
  basepath: __dirname,
  specification: {
    "title": "Test Title",
    // ...
  }
});
```

## OS Support

Currently the only supported os is Mac OS X.

Track the status of this here: https://github.com/LinusU/node-appdmg/issues/14

## Hidden files

By default hidden files will show for users with `com.apple.finder AppleShowAllFiles`
set to `TRUE`. This can be worked around by moving all hidden files outside the initial
window size (using `"type": "position"`), this has the side-effect of enabling a scrollbar.

Files to usually move:

- `.background`
- `.DS_Store`
- `.Trashes`
- `.VolumeIcon.icns`

## Alternatives

- [create-dmg](https://github.com/andreyvit/create-dmg/blob/master/README.md), a Bash script
- [dmgbuild](https://pypi.python.org/pypi/dmgbuild), a Python version

---
_Source: https://npm.io/package/appdmg · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._