@davincidreams/codepen-tools

AI SDK tools for CodePen integration - Create, embed, and manage CodePen pens programmatically with LLMs.

Overview

This package provides a comprehensive set of tools for working with CodePen through the AI SDK. These tools enable AI/LLM systems to create interactive web components, generate embed codes, and manage CodePen resources programmatically.

$3

| Tool | Description |
|------|-------------|
| codepenTool | Create CodePen pens using the prefill API |
| codepenEmbedTool | Generate CodePen embed HTML code |
| codepenOembedTool | Generate CodePen OEmbed API URLs |
| codepenUrlExtensionsTool | Generate CodePen URL extensions for raw code, screenshots, and custom editor layouts |

Installation

``bash
pnpm add @davincidreams/codepen-tools
`

Tools

$3

Create CodePen pens using the CodePen prefill API. Generates a URL that can be used to fork or view the pen.

Parameters:
- html (string, optional): HTML content for the CodePen
- css (string, optional): CSS content for the CodePen
- js (string, optional): JavaScript content for the CodePen
- editors (string, default: "111"): Which editors to show (e.g., "101" for HTML+CSS, "111" for all three)
- title (string, optional): Optional title for the CodePen
- description (string, optional): Optional description for the CodePen

Example:
`typescript
import { codepenTool } from '@davincidreams/codepen-tools';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await generateText({
model: openai('gpt-4'),
prompt: 'Create a beautiful button component with hover effects',
tools: {
codepenTool,
},
});

console.log(result.toolCalls);
// Returns: {
// success: true,
// url: 'https://codepen.io/pen/define/?data=...',
// data: { html: '...', css: '...', js: '...' }
// }
`

$3

Generate CodePen embed HTML code for embedding Pens in websites. Supports customization of theme, height, default tabs, editable mode, and preview mode.

Parameters:
- penId (string, required): The Pen ID or slug (e.g., "abc123" from codepen.io/username/pen/abc123)
- username (string, optional): The username of the Pen author
- height (number, default: 300): Height of the embed in pixels
- themeId (string/number, optional): Theme ID or keyword ("light", "dark", or numeric ID)
- defaultTab (string, default: "result"): Default tab to show (e.g., "result", "html,result", "css,result")
- editable (boolean, default: false): Whether the embed is editable
- preview (boolean, default: false): Whether to use click-to-play preview mode
- clickToLoad (boolean, default: false): Whether to use click-to-load mode
- title (string, optional): Optional title for the embed
- description (string, optional): Optional description for the embed

Example:
`typescript
import { codepenEmbedTool } from '@davincidreams/codepen-tools';

const result = await generateText({
model: openai('gpt-4'),
prompt: 'Generate an embed code for the pen with ID "abc123" from user "johndoe"',
tools: {
codepenEmbedTool,
},
});

console.log(result.toolCalls);
// Returns: {
// success: true,
// embedHtml: '',
// scriptEmbedHtml: '

...

',
// embedUrl: 'https://codepen.io/johndoe/pen/abc123?...'
// }
`

$3

Generate CodePen OEmbed API URLs and optionally fetch OEmbed data. OEmbed allows automatic embedding of CodePen Pens in platforms like WordPress, Medium, and Notion.

Parameters:
- penUrl (string, required): The full CodePen Pen URL (e.g., "https://codepen.io/username/pen/abc123")
- format (enum: "json" | "js", default: "json"): Response format
- callback (string, optional): Callback function name for JSONP format (required when format="js")
- height (number, optional): Custom height for the embed iframe in pixels
- fetch (boolean, default: false): Whether to fetch the actual OEmbed data from CodePen API

Example:
`typescript
import { codepenOembedTool } from '@davincidreams/codepen-tools';

const result = await generateText({
model: openai('gpt-4'),
prompt: 'Get the OEmbed data for this CodePen: https://codepen.io/johndoe/pen/abc123',
tools: {
codepenOembedTool,
},
});

console.log(result.toolCalls);
// Returns: {
// success: true,
// oembedUrl: 'https://codepen.io/api/oembed?url=...&format=json',
// data: { / OEmbed response if fetch=true / }
// }
`

$3

Generate CodePen URL extensions for accessing raw code, preprocessed code, screenshots, and custom editor layouts. Useful for linking code between Pens or getting Pen assets.

Parameters:
- penUrl (string, required): The full CodePen Pen URL (e.g., "https://codepen.io/username/pen/abc123")
- extensionType (enum: "code" | "screenshot" | "editor", required): Type of URL extension
- codeType (enum, optional): Code type for raw/preprocessed code access (required when extensionType="code")
- screenshotSize (enum: "large" | "small", optional): Screenshot size (required when extensionType="screenshot")
- layout (enum: "left" | "right" | "top", optional): Editor layout (for extensionType="editor")
- editors (string, optional): Which editors to show as a 4-digit string (for extensionType="editor")

Example:
`typescript
import { codepenUrlExtensionsTool } from '@davincidreams/codepen-tools';

const result = await generateText({
model: openai('gpt-4'),
prompt: 'Get the raw CSS code from this pen: https://codepen.io/johndoe/pen/abc123',
tools: {
codepenUrlExtensionsTool,
},
});

console.log(result.toolCalls);
// Returns: {
// success: true,
// url: 'https://codepen.io/johndoe/pen/abc123.css',
// extensionType: 'code',
// additionalUrls: { / related URLs / }
// }
`

Usage

$3

`typescript
import { codepenTool } from '@davincidreams/codepen-tools';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await generateText({
model: openai('gpt-4'),
prompt: 'Create a simple card component with shadow and hover effects',
tools: {
codepenTool,
},
});

console.log(result.text);
console.log(result.toolCalls);
`

$3

`typescript
import {
codepenTool,
codepenEmbedTool,
codepenOembedTool,
codepenUrlExtensionsTool
} from '@davincidreams/codepen-tools';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await generateText({
model: openai('gpt-4'),
prompt: 'Create a navigation bar, then generate an embed code for it',
tools: {
codepenTool,
codepenEmbedTool,
codepenOembedTool,
codepenUrlExtensionsTool,
},
});
`

Documentation

For more detailed information about each tool, see the documentation files in the docs/ folder:

- codepenPOSTtoPrefill.md - Detailed guide on creating CodePen pens via prefill API
- codepenEmbedPrefill.md - Embed options and customization guide
- codepenOembed.md - OEmbed API documentation
- codepenURLextensions.md - URL extensions reference
- codepenLimitations.md - Known limitations and constraints

LLM Integration Guide

For comprehensive guidance on using these tools with AI/LLM systems, see codepen-skill.md. This guide includes:

- How to use each tool effectively with LLMs
- Example prompts and responses
- Best practices for generating UI components
- Workflow examples
- Tips for effective tool usage

Development

`bash


Install dependencies

pnpm install

Build the package

pnpm build

Type-check

pnpm type-check

Watch mode

pnpm dev
`

Publishing

1. Update the version in package.json
2. Build the package: pnpm build
3. Publish to npm: pnpm publish --access public`
4. Your tools will appear on tpmjs.com within 2-15 minutes

License

MIT