Skip to content
This repository has been archived by the owner. It is now read-only.
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Sketch File Format TS

⚠️ This repository has been merged into the sketch-document monorepo which contains both JSON Schema and TypeScript types. The latest npm package is published to @sketch-hq/sketch-file-format-ts

TypeScript types for the Sketch File Format


This repo contains TypeScript types automatically generated from the Sketch File Format JSON Schemas.

Types are maintained and exported for each Sketch File Format major version. See usage instructions below for more information.

Use cases

  • Strongly type objects representing Sketch documents, or fragments of Sketch documents in TypeScript projects

Related projects


Add the npm module using npm or yarn

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

Types for the latest file format are on the default export

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

Types for historical file formats are accessible via named exports

import { FileFormat1, FileFormat2 } from '@sketch-hq/sketch-file-format-ts'

Read about how file format versions map to Sketch document versions here


Create a typed layer blur object

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,

Layer types can be narrowed using discriminate properties on the helper union types like AnyLayer

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

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

Work with representations of Sketch files that could have a range of document versions

import {
} from '@sketch-hq/sketch-file-format-ts'

const processDocumentContents = (
  contents: FileFormat1.Contents | FileFormat2.Contents | FileFormat3.Contents,
) => {
  if (contents.meta.version === 119) {
    // type narrowed to file format v1, i.e. Sketch documents with version 119


This section of the readme is related to developing the file format spec. If you just want to consume the schemas you can safely ignore this.


The scripts/generate.ts ingests the file format JSON Schema, and generates type definitions using the TypeScript compiler API.

We depend on multiple major versions of the schemas in package.json using yarn aliases, and generate types for each one. This means that users that have to implement multiple versions of the file format don't need to manually manage multiple versions of this package.


Script Description
yarn build Builds the project into the dist folder
yarn test Build script unit tests
yarn format-check Checks the repo with Prettier


Conventional commits

Try and use the conventional commits convention when writing commit messages.

Changing how the types are generated

  1. Update scripts/generate.ts
  2. Unit test your changes
  3. Determine the semver bump type and call yarn changeset to create an intent to release your changes (read more about changesets here).
  4. Open a PR to main

Adding or updating a file format version

  1. Use the yarn aliases syntax to add new schema version
  2. Use exact semvers, for example to update or add v3 of the schemas as 3.4.3 run,
    yarn add @sketch-hq/sketch-file-format-3@npm:@sketch-hq/sketch-file-format@3.4.3
  3. If the schema version is new to the repo you'll also need to update the index.ts to export the types, and scripts/generate.ts to generate the new types
  4. Open a PR to main


  1. Merge the release PR maintained by the changesets GitHub Action.