@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.

Available Tools

| 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

pnpm add @davincidreams/codepen-tools

Tools

codepenTool

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:

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: '...' }
// }

codepenEmbedTool

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:

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: '<iframe src="..." style="..."></iframe>',
//   scriptEmbedHtml: '<p class="codepen" data-slug-hash="abc123">...</p>',
//   embedUrl: 'https://codepen.io/johndoe/pen/abc123?...'
// }

codepenOembedTool

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:

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 */ }
// }

codepenUrlExtensionsTool

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:

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

Basic Example with Single Tool

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);

Using Multiple Tools

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

# 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