smartquote

Smart quote conversion utilities and ESLint plugin for typographically correct quotes.

Converts straight quotes (" and ') to their curly/smart equivalents (" " ' ').

Installation

``bash
npm install smartquote


or


pnpm add smartquote
`

Quick Start

`typescript
import { smartQuotes, SmartQuote } from 'smartquote';

const result = smartQuotes('She said "hello"');
// result === 'She said "hello"'

// Verify with constants
result.startsWith(She said ${SmartQuote.LeftDouble}); // true
`

API Reference

$3

Converts straight quotes to smart quotes using context-aware rules.

`typescript
import { smartQuotes, SmartQuote } from 'smartquote';
const { LeftDouble, RightDouble, RightSingle } = SmartQuote;

// Basic conversion
smartQuotes('"hello"');
// === ${LeftDouble}hello${RightDouble}

// Apostrophes are detected between letters
smartQuotes("It's wonderful");
// === It${RightSingle}s wonderful

// Nested quotes work correctly
smartQuotes(He said "She told me 'yes'");
// Outer double quotes, inner single quotes
`

$3

Markdown-aware conversion that preserves straight quotes inside code blocks.

`typescript
import { smartQuoteMarkdown } from 'smartquote';

const markdown =
"This quote converts," she said.

\\\javascript
const x = "stays straight";
\\\

Use \"straight"\ in inline code.
;

const result = smartQuoteMarkdown(markdown);
// Prose gets smart quotes; code blocks are unchanged
`

Preserved regions:
- Fenced code blocks ( `` )
- Inline code (` `)
- Indented code blocks (4 spaces or tab)

$3

Constants using Unicode escapes (immune to LLM normalization):

`typescript
import { SmartQuote } from 'smartquote';

SmartQuote.LeftDouble // \u201C "
SmartQuote.RightDouble // \u201D "
SmartQuote.LeftSingle // \u2018 '
SmartQuote.RightSingle // \u2019 '
SmartQuote.StraightDouble // \u0022 "
SmartQuote.StraightSingle // \u0027 '
`

Streaming API

For processing text streams (like AI chat responses) without re-processing already-converted content.

$3

Wraps an AsyncIterable to convert quotes on the fly. Use this for plain text streams.

`typescript
import { smartQuoteAsyncIterable } from 'smartquote';

for await (const chunk of smartQuoteAsyncIterable(textStream)) {
process.stdout.write(chunk);
}

// Disable markdown-aware conversion (converts quotes even in code blocks)
for await (const chunk of smartQuoteAsyncIterable(textStream, { disableMarkdown: true })) {
process.stdout.write(chunk);
}
`

$3

Returns a generic TransformStream for structured stream parts with a text-delta type.

`typescript
import { smartQuoteTransform } from 'smartquote';

// Works with any stream of { type: 'text-delta', textDelta: string } parts
const stream = someTextStream.pipeThrough(smartQuoteTransform());

// Disable markdown-aware conversion
const stream = someTextStream.pipeThrough(smartQuoteTransform({ disableMarkdown: true }));
`

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| disableMarkdown | boolean | false | When false, preserves straight quotes inside code blocks. Set to true to convert all quotes. |

Why streaming buffers trailing quotes: When a chunk ends with ' (e.g., "don'"), we can't determine if it's an apostrophe or closing quote until the next chunk arrives. Both streaming APIs handle this automatically.

Vercel AI SDK Integration

For Vercel AI SDK v5+, use the dedicated smartquote/ai-sdk entry point which provides properly typed transforms:

`bash
npm install smartquote ai@>=5.0.0
`

`typescript
// app/api/chat/route.ts
import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { smartQuoteTransform } from 'smartquote/ai-sdk';

export async function POST(req: Request) {
const { messages } = await req.json();

const result = streamText({
model: anthropic('claude-sonnet-4-20250514'),
messages,
experimental_transform: smartQuoteTransform(),
});

return result.toDataStreamResponse();
}
`

The smartquote/ai-sdk module exports:
- smartQuoteTransform - Typed for StreamTextTransform
- smartQuotes - Re-exported for convenience
- SmartQuote - Re-exported for convenience

ESLint Plugin

Enforce smart quotes in JSX/TSX at build time.

`javascript
// eslint.config.js
import { plugin as smartQuotesPlugin } from 'smartquote/eslint';

export default [
{
files: ['/.tsx', '/.jsx'],
plugins: {
smartquote: smartQuotesPlugin,
},
rules: {
'smartquote/smart-quotes': 'error',
},
},
];
`

$3

- JSX text content:

Click "here"

(always user-facing)
- Allowlisted props: placeholder, title, alt, label, aria-label, aria-placeholder, aria-roledescription, aria-valuetext

Non-user-facing props (className, href, id, key, etc.) are ignored.

$3

`javascript
// Add props to the default allowlist
'smartquote/smart-quotes': ['error', {
additionalProps: ['data-tooltip', 'data-label']
}]

// Override defaults entirely
'smartquote/smart-quotes': ['error', {
props: ['placeholder', 'title']
}]
`

$3

Run eslint --fix to automatically convert straight quotes to smart quotes in JSX.

Algorithm

Based on the algorithm from pensee.com/dunham/smartQuotes.html.

Opening quotes are used when:
1. At the beginning of text
2. After whitespace (space, tab, newline)
3. After left punctuation: ( [ { <
4. After an opening quote of the opposite type (nested quotes)

Closing quotes are used in all other cases.

Apostrophes are detected when a single quote appears between two letters (don't, it's`).

Performance

The streaming API processes chunks incrementally (O(n) total) rather than re-processing accumulated text (O(n²)). For long AI responses, this can be 100x+ faster.

License

MIT