FunctionOptionaloptions: {Configuration options for the builder
Optionalstrict?: booleanIf true, throws errors for invalid data. Otherwise gracefully handles nulls.
OptionallimitNesting?: booleanIf true, limits nested children to 2 levels (Notion API limit).
OptionallimitChildren?: booleanIf true, limits children arrays to 100 blocks, putting excess in additionalBlocks.
OptionalallowBlankParagraphs?: booleanIf true, allows empty paragraph blocks.
OptionalhandleTemplatePageChildren?: booleanIf true, automatically moves all children blocks to additionalBlocks when a template is applied (type is not "none"). This is required because the Notion API doesn't allow children blocks in page creation requests that apply templates.
A builder object with fluent interface methods for constructing Notion content.
// Basic page creation
const page = createNotionBuilder()
.parentDataSource('data-source-id')
.title('Name', 'My Task')
.select('Status', 'In Progress')
.date('Due Date', '2024-12-01')
.paragraph('This is a task description.')
.toDo('Complete the first step', false)
.toDo('Review with team', false)
.build();
// Complex nested structure
const complexPage = createNotionBuilder()
.parentDataSource('data-source-id')
.title('Project Name', 'Website Redesign')
.heading1('Project Overview')
.paragraph('This project involves redesigning our main website.')
.heading2('Phase 1: Research')
.startParent(toggle('Research Tasks', []))
.toDo('Conduct user interviews', false)
.toDo('Analyze competitor websites', false)
.endParent()
.heading2('Phase 2: Design')
.callout('Important: Get stakeholder approval before development', '⚠️')
.build();
// Handle large content with additionalBlocks
const result = page.content;
const extraBlocks = page.additionalBlocks;
// Create page first, then append additional blocks if needed
const notion = new Client({ auth: process.env.NOTION_TOKEN });
const newPage = await notion.pages.create(result);
if (extraBlocks && extraBlocks.length > 0) {
for (const blockChunk of extraBlocks) {
await notion.blocks.children.append({
block_id: newPage.id,
children: blockChunk
});
}
}
// Using template with automatic children handling
const templatePage = createNotionBuilder({ handleTemplatePageChildren: true })
.parentDataSource('data-source-id')
.template('default') // or template_id
.title('Name', 'Task from Template')
.paragraph('This content will be moved to additionalBlocks')
.toDo('Complete task', false)
.build();
// Create page with template, then append children
const notion = new Client({ auth: process.env.NOTION_TOKEN });
const newPage = await notion.pages.create(templatePage.content);
// Append the children that were moved to additionalBlocks
if (templatePage.additionalBlocks && templatePage.additionalBlocks.length > 0) {
for (const blockChunk of templatePage.additionalBlocks) {
await notion.blocks.children.append({
block_id: newPage.id,
children: blockChunk
});
}
}
Creates a fluent interface builder for constructing Notion objects, including pages, properties, and blocks.
Fluent Interface Methods:
The returned builder provides chainable methods organized into categories:
Page Setup Methods:
parentDataSource(data_source_id)- Sets parent data sourceparentDs(data_source_id)- Alias for parentDataSource()parentPage(page_id)- Sets parent pageparentDatabase(database_id)- Sets parent database (deprecated, will not work in databases with more than one data source)parentDb(database_id)- Alias for parentDatabase() (deprecated, will not work in databases with more than one data source)pageId(page_id)- Adds page ID for updatesblockId(block_id)- Adds block ID for block operationspropertyId(property_id)- Adds property ID for property operationscover(url)- Sets page cover imageicon(url)- Sets page iconProperty Methods:
property(name, type, value)- Adds custom propertytitle(name, value)- Adds title propertyrichText(name, value)- Adds rich text propertycheckbox(name, value)- Adds checkbox propertydate(name, value)- Adds date propertyemail(name, value)- Adds email propertyfiles(name, value)- Adds files propertymultiSelect(name, value)- Adds multi-select propertynumber(name, value)- Adds number propertypeople(name, value)- Adds people propertyphoneNumber(name, value)- Adds phone number propertyrelation(name, value)- Adds relation propertyselect(name, value)- Adds select propertystatus(name, value)- Adds status propertyurl(name, value)- Adds URL propertyBlock Methods:
paragraph(content, options, url)- Adds paragraph blockheading1(content, options, url)- Adds H1 blockheading2(content, options, url)- Adds H2 blockheading3(content, options, url)- Adds H3 blockbulletedListItem(content, options, url)- Adds bulleted list itemnumberedListItem(content, options, url)- Adds numbered list itemtoDo(content, checked, options, url)- Adds to-do blockcallout(content, emoji, options, url)- Adds callout blockquote(content, options, url)- Adds quote blockcode(content, language)- Adds code blockdivider()- Adds divider blockimage(url, caption)- Adds image blockvideo(url, caption)- Adds video blockaudio(url, caption)- Adds audio blockfile(url, caption)- Adds file blockpdf(url, caption)- Adds PDF blockbookmark(url, caption)- Adds bookmark blockembed(url, caption)- Adds embed blocktable(tableArray)- Adds table blocktableRow(cellContents)- Adds table rowcolumnList(columnArray)- Adds column listcolumn(columnContent)- Adds columntoggle(content, children, options, url)- Adds toggle blockStructure Management:
startParent(parentBlock)- Begins nested block structureendParent()- Ends current nesting levelbuild()- Finalizes and returns the built objectReturn Object:
Returns an object with two possible properties:
content(always returned) - can be a full page object, an array of blocks, or a properties objectadditionalBlocks- array containing block chunks that exceed Notion's limits for subsequent requestscreateNotionBuilder