bookcover-core — schema reference
Part of the bookcover generation system.
This is the core generator package — not used directly. Install
bookcover-node for Node.js or
bookcover-web for the browser.
This document describes the schema accepted by both.
All colors must be HSL strings in the format hsl(200deg, 50%, 30%).
Printing / size
| Field | Type | Notes |
|---|
service_id | string | Printing service: kdp, lulu, officeworks, vistaprint_au, ctrlprint |
binding_type | string | e.g. paperback, hardcover — depends on service |
size_id | string? | e.g. us_trade, a5 — omit if using custom dimensions |
page_count | number? | Required when using size_id |
ink_type | string? | e.g. bw, color — required by some services |
paper_type | string? | e.g. white, cream — required by some services |
custom_unit | string? | mm or in — for custom dimensions |
custom_trim_width | number? | Trim width in custom_unit |
custom_trim_height | number? | Trim height in custom_unit |
custom_bleed | number? | Bleed in custom_unit |
custom_spine | number? | Spine width in custom_unit |
margin_front | number? | Front panel text margin as % of trim height |
margin_back | number? | Back panel text margin as % of trim height |
Title
Three title lines (title1, title2, title3) each share the same set of options.
title1 is the main title.
| Field | Type | Notes |
|---|
title1 | string | Main title (default '') |
title1_font | {family: string}? | Font family name as used in Typst |
title1_size | number? | Relative size multiplier (default 1.0) |
title1_weight | number? | CSS-style weight 100–900 (default 700) |
title1_italic | boolean? | |
title1_color | hsl? | Defaults to contrasting color vs bg_color |
title_alignment | center|left|right? | |
title_position | top|middle|bottom | Required |
title_spacing | number? | Gap between title lines as % of trim height |
title_margin_top | number? | Top margin as % of trim height |
title_margin_bottom | number? | Bottom margin as % of trim height |
title2 and title3 have the same _font, _size, _weight, _italic, _color fields;
title2/title3 color defaults to title1_color.
Subtitle
| Field | Type | Notes |
|---|
subtitle | string | (default '') |
subtitle_font | {family: string}? | |
subtitle_size | number? | |
subtitle_weight | number? | 100–900 |
subtitle_italic | boolean? | |
subtitle_color | hsl? | |
subtitle_alignment | center|left|right? | |
subtitle_position | top|middle|bottom | Required |
subtitle_spacing | number? | Gap between subtitle lines as % of trim height |
subtitle_margin_top | number? | |
subtitle_margin_bottom | number? | |
Author
| Field | Type | Notes |
|---|
author | string | (default '') |
author_font | {family: string}? | |
author_size | number? | |
author_weight | number? | 100–900 |
author_italic | boolean? | |
author_color | hsl? | |
author_alignment | center|left|right? | |
author_position | top|middle|bottom | Required |
author_margin_top | number? | |
author_margin_bottom | number? | |
Blurb (back panel)
| Field | Type | Notes |
|---|
blurb | string | Back cover text (default '') |
blurb_font | {family: string}? | |
blurb_size | number? | |
blurb_color | hsl? | |
blurb_bg_color | hsl|null? | undefined = derive from bg_color; null = transparent |
blurb_alignment | center|left|right|justified? | |
blurb_padding | number? | Padding as % of trim height |
blurb_width | number? | Width as % of face width |
blurb_spacing | number? | Line spacing multiplier (1 = default Typst leading) |
Spine
Spine text defaults to the front title and author if not set. Pass '' to explicitly
suppress spine text.
| Field | Type | Notes |
|---|
spine_title | string? | Omit to derive from title1; '' to suppress |
spine_title_font | {family: string}? | |
spine_title_size | number? | |
spine_title_weight | number? | |
spine_title_italic | boolean? | |
spine_title_color | hsl? | |
spine_author | string? | Omit to derive from author; '' to suppress |
spine_author_font | {family: string}? | |
spine_author_size | number? | |
spine_author_weight | number? | |
spine_author_italic | boolean? | |
spine_author_color | hsl? | |
spine_color | hsl|null? | null = no separate spine color (uses primary bg) |
Background
| Field | Type | Notes |
|---|
bg_color | hsl? | Primary background color |
bg_color_gradient | boolean? | Apply gradient to background |
bg_image_coverage | full|front|painted|feature|front_partial? | How the background image is placed |
icon_id | string? | Iconify ID (e.g. game-icons:sailboat) or raw SVG |
icon_mode | center|offset|echo|background? | |
icon_size | number? | Relative size multiplier, range 0.25–4 |
icon_color | string? | |
icon_spine | boolean? | Show icon on spine |
pattern | string? | Raw SVG string tiled as background pattern |
pattern_tile_mm | number? | Pattern tile size in mm (default 80) |
pattern_color | string? | |
Other
| Field | Type | Notes |
|---|
isbn | string | ISBN-13; generates barcode on back cover (default '') |