sketch-hqSketch File Format TS
Contains TypeScript types automatically generated from the Sketch File Format JSON Schemas.
Overview
Types are maintained and exported for each Sketch File Format major version. See usage instructions below for more information.
Usage
Add the npm module using npm or yarn
npm install @sketch-hq/sketch-file-format-tsTypes for the latest file format are on the default export
import FileFormat from '@sketch-hq/sketch-file-format-ts'Read about how file format versions map to Sketch document versions here
Examples
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 layers.map((layer) => {
switch (layer._class) {
case 'bitmap':
// type narrowed to Bitmap layers
case 'star':
// type narrowed to Star layers
}
})
}Development
Following is further information for making changes to how the types are generated.
Approach
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.
Please note that the latest version of the schemas is referenced directly within the monorepo and not using aliases.
Scripts
| 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 |
Workflows
Conventional commits
Try and use the conventional commits convention when writing commit messages.
Changing how the types are generated
- Update
scripts/generate.ts - Unit test your changes
- Determine the semver bump type and call yarn changeset to create an intent to release your changes (read more about changesets here).
- Open a PR to
main
Adding or updating a file format version
- Use the yarn aliases syntax to add new schema version
- Use exact semvers, for example to update or add v3 of the schemas as
3.4.3run,yarn add @sketch-hq/sketch-file-format-3@npm:@sketch-hq/sketch-file-format@3.4.3 - If the schema version is new to the repo you'll also need to update the
index.tsto export the types, andscripts/generate.tsto generate the new types - Open a PR to
main