Sketch Document Utilities

The build process transforms hand-editable YAML source files into valid JSON Schema output. During this process, several transformations are applied to increase schema strictness:

• Abstract schemas: Used in YAML to maintain DRYness; these are processed out during the build.
• Additional properties: While JSON Schema defaults additionalProperties to true, the build process sets it to false on every object schema unless explicitly specified otherwise, to increase strictness.
• Required properties: The build process automatically sets every object property as required. To define a property as genuinely optional, use the non-standard optional keyword in the YAML source; this keyword is removed during the build.

To use the Sketch file format JSON schemas in your project, install the @sketch-hq/sketch-file-format package using npm or yarn.

npm install @sketch-hq/sketch-file-format

To use the automatically generated TypeScript types for the Sketch File Format, install the package via npm or yarn.

npm install @sketch-hq/sketch-file-format-ts

To update the schemas, follow these steps:

1. Update the schema YAML source files.
2. Run yarn validate-schemas to ensure changes are valid JSON Schema Draft 7.
3. Run yarn validate-file and yarn validate-reference-files to test against real Sketch files.
4. Determine the appropriate semver bump type and run yarn changeset to create a release intent.
5. Open a PR to main.

To generate the schemas from the YAML source files in the dist folder, follow these steps:

1. Ensure you have modern versions of Yarn and Node installed.
2. Check out the repository.
3. Run yarn to set up dependencies.
4. Run yarn build to generate the schemas into the dist folder.

If you need to download the built JSON schemas directly without installing the npm package, they are available via unpkg at the following location:

https://unpkg.com/browse/@sketch-hq/sketch-file-format@latest/dist/

The TypeScript types in this package are generated from the JSON Schema definitions in @sketch-hq/sketch-file-format. To ensure you are using the latest schemas, you should follow one of these two workflows:

1. Full Monorepo Build: Run yarn build from the monorepo root. This builds @sketch-hq/sketch-file-format first and then generates the TypeScript types.
2. Type-only Generation: Run yarn generate from the file-format-ts directory. This generates only the TypeScript types based on the existing build of the schemas.

# From monorepo root to build everything including types
yarn build

# From packages/file-format-ts to generate only types
yarn generate

You can use the FileFormat namespace to create strictly typed objects, such as a Blur object, ensuring all required properties like _class, isEnabled, and type are present.

import FileFormat from '@sketch-hq/sketch-file-format-ts'

const blur: FileFormat.Blur = {
  _class: 'blur',
  isEnabled: false,
  center: '{0.5, 0.5}',
  motionAngle: 0,
  radius: 10,
  saturation: 1,
  type: FileFormat.BlurType.Gaussian,
}

After installing the package, you can import the schemas object to access the JSON Schema definitions. This object contains the schemas for different parts of a Sketch file (like document, page, or meta) and version information.

import schemas from '@sketch-hq/sketch-file-format'

// schemas contains properties like:
// schemas.version: Latest supported Sketch document version
// schemas.document: JSONSchema7 for the document JSON entry
// schemas.page: JSONSchema7 for page JSON entries

The package provides helper union types like AnyLayer. You can use the _class property as a discriminant within a switch statement to narrow the type of a layer to its specific implementation (e.g., Bitmap or Star).

import FileFormat from '@sketch-hq/sketch-file-format-ts'

const mapLayers = (layers: FileFormat.AnyLayer[]) => {
  return layers.map((layer) => {
    switch (layer._class) {
      case 'bitmap':
      // type narrowed to Bitmap layers
      case 'star':
      // type narrowed to Star layers
    }
  })
}

The types for the latest file format version are available on the default export of the module.

import FileFormat from '@sketch-hq/sketch-file-format-ts'

Use the toFile function to save changes back to a .sketch file. To use this, you must provide a SketchFile object which contains both the modified contents and the original filepath.

import { fromFile, SketchFile, toFile } from '@sketch-hq/sketch-file'
import { resolve } from 'path'

const sketchDocumentPath = './artboards-with-background.sketch'

fromFile(resolve(__dirname, sketchDocumentPath)).then((parsedFile) => {
  // ... perform modifications on parsedFile.contents ...

  const exportableFile: SketchFile = {
    contents: parsedFile.contents,
    filepath: sketchDocumentPath,
  }
  
  toFile(exportableFile)
})