Seeding the Database - digitalgroundgame/pragmatic-papers GitHub Wiki

← Table of Contents

Overview

Seed scripts populate the database with sample content for development.

How to Seed

  1. Navigate to http://localhost:8000/admin
  2. Click Seed your database
  3. Wait for all steps of seeding to complete.
  4. You now have a fully populated Local Development Postgres Database.

[!TIP] You can re-seed the database by simply refreshing the page. The first step of seeding is always to clean up everything it may have previously created.

Creating Seeds

Most Issues and Pull Requests wont require seed articles. A general rule of thumb is: If your issue is a feature, and it requires migrations, then the project would likely benefit from having said feature documented.

Seed creation is a great use case for AI Agents. Simply ask the agent to create a seeding article for your new feature. Review the results to ensure the feature demonstration article meets your requirements. When your Pull Request is reviewed, reviewers can use your seed article to test the behavior of your new feature.

Utility Functions

Rich Text Utilities (richtext.ts)

Basic Functions:

  • createTextNode(text, format?) - Creates a text node
  • createParagraph(text | textNode | array) - Creates a paragraph with text/nodes
  • createEmptyParagraph() - Creates a line break paragraph
  • createRichText(children) - Wraps paragraph nodes in root structure

High-Level Functions:

  • createRichTextFromString(text) - Single paragraph from string
  • createRichTextFromParagraphs(paragraphs[], addSpacing?) - Multiple paragraphs with auto-spacing
  • createLoremIpsumContent(numParagraphs) - Lorem ipsum for testing

Lorem Ipsum Generators:

  • generateLoremIpsumParagraph(numSentences) - Single paragraph
  • generateLoremIpsumParagraphs(numParagraphs) - Array of paragraphs

Media Utilities (media.ts)

  • fetchFileByURL(url) - Fetches a file from URL, returns Payload File object
  • createMediaFromURL(payload, url, alt, additionalData?) - Fetches and creates media in one call
    • additionalData supports: { caption: LexicalContent }

Article Utilities (articles.ts)

  • createArticle(payload, options) - Creates a published article with defaults
  • validateWriters(writers) - Throws if no writers provided
  • getWriterOrThrow(writers, index) - Gets writer by index with validation

Block Helpers (in feature files)

Media Blocks:

createMediaBlock(mediaId) // Single image block

Media Collage Blocks:

createMediaCollageBlock(mediaIds[], layout) // 'grid' or 'carousel'

TODO

  • Add createFootnotesBlock
  • Add createMathBlock
  • Export createSocialEmbedBlock