Starry Night

https://github.com/wooorm/starry-night
Admin
Starry Night is an open-source syntax highlighter that supports 600+ grammars using TextMate...
Tokens:33,354
Snippets:396
Trust Score:9.6
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Starry Night

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Installation commands for Node.js and import examples for Deno and browsers.

```sh
npm install @wooorm/starry-night
```

```js
import {common, createStarryNight} from 'https://esm.sh/@wooorm/starry-night@3'
```

```html
<script type="module">
  import {common, createStarryNight} from 'https://esm.sh/@wooorm/starry-night@3?bundle'
</script>
```

--------------------------------

### Browser setup without build tools

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

A complete HTML example using ESM imports to highlight code directly in the browser.

```html
<!doctype html>
<html>
<head>
  <link rel="stylesheet" href="https://esm.sh/@wooorm/starry-night@3/style/both">
</head>
<body>
<pre><code id="code"></code></pre>

<script type="module">
  import {common, createStarryNight} from 'https://esm.sh/@wooorm/starry-night@3?bundle'
  import {toHtml} from 'https://esm.sh/hast-util-to-html@9?bundle'

  const starryNight = await createStarryNight(common)
  const code = 'const x = 1'
  const scope = starryNight.flagToScope('js')
  const tree = starryNight.highlight(code, scope)
  
  document.getElementById('code').innerHTML = toHtml(tree)
</script>
</body>
</html>
```

--------------------------------

### Highlight Code

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Basic usage example for initializing the highlighter and processing a string of code.

```js
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)

const scope = starryNight.flagToScope('markdown')
const tree = starryNight.highlight('# hi', scope)

console.log(tree)
```

```js
{
  type: 'root',
  children: [
    {
      type: 'element',
      tagName: 'span',
      properties: {className: ['pl-mh']},
      children: [
        {type: 'text', value: '# '},
        {
          type: 'element',
          tagName: 'span',
          properties: {className: ['pl-en']},
          children: [{type: 'text', value: 'hi'}]
        }
      ]
    }
  ]
}
```

--------------------------------

### Install Starry Night

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/README.md

Install the package via npm.

```bash
npm install @wooorm/starry-night
```

--------------------------------

### Highlight Method Result Example

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/hast-output-format.md

Example of the object structure returned by the highlight method.

```javascript
const tree = starryNight.highlight('const x = 1', 'source.js')
// Result:
// {
//   type: 'root',
//   children: [
//     {type: 'element', tagName: 'span', properties: {className: ['pl-k']}, children: [...]},
//     ...
//   ]
// }
```

--------------------------------

### HTML Output Example

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

The resulting HTML output with syntax highlighting classes applied.

```html
<span class="pl-mh"><span class="pl-mh">#</span><span class="pl-mh"> </span>Hello, world!</span>
```

--------------------------------

### Execute line number utility

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Example module demonstrating how to apply the gutter utility to a highlighted tree.

```js
import {common, createStarryNight} from '@wooorm/starry-night'
import {toHtml} from 'hast-util-to-html'
import {starryNightGutter} from './hast-util-starry-night-gutter.js'

const starryNight = await createStarryNight(common)

const tree = starryNight.highlight(
  '# Some heading\n\n```js\nalert(1)\n```\n***',
  'text.md'
)

starryNightGutter(tree)

console.log(toHtml(tree))
```

--------------------------------

### Markdown Input Example

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Example of raw markdown text used as input for syntax highlighting.

```markdown
# Hello, world!
```

--------------------------------

### JavaScript Grammar Example

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

An example implementation of the Grammar interface for JavaScript.

```typescript
{
  scopeName: 'source.js',
  names: ['javascript', 'js'],
  extensions: ['.js', 'js'],
  patterns: [
    {include: '#comments'},
    {include: '#strings'},
    {include: '#keywords'},
    // ... more pattern definitions
  ],
  repository: {
    comments: {
      begin: '(//)(.*)$',
      beginCaptures: {
        1: {name: 'punctuation.definition.comment'},
        2: {name: 'comment.line.double-slash'}
      },
      patterns: []
    },
    // ... more named patterns
  }
}
```

--------------------------------

### Initialize and use Starry Night

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/api-reference.md

Basic usage example showing how to instantiate the highlighter and perform a code highlight operation.

```javascript
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)

const scope = starryNight.flagToScope('javascript')
const tree = starryNight.highlight('console.log(1)', scope)
console.log(tree)
```

--------------------------------

### Markdown input for unified pipeline

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Sample markdown file content used for the unified integration example.

```markdown
# Hello

…world!

```js
console.log('it works!')
```
```

--------------------------------

### Integrate with unified, remark, and rehype

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Example showing how to use rehype-starry-night within a unified processing pipeline.

```js
import fs from 'node:fs/promises'
import rehypeStarryNight from 'rehype-starry-night'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeStarryNight)
  .use(rehypeStringify)
  .process(await fs.readFile('example.md'))

console.log(String(file))
```

--------------------------------

### Resolve dependency version mismatches

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

Check installed versions and install the compatible version of vscode-oniguruma.

```bash
npm ls vscode-oniguruma
npm install vscode-oniguruma@2 --save
```

--------------------------------

### Example Include Rule

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

A rule referencing a definition from the repository.

```typescript
{
  include: '#comments'  // Includes from repository
}
```

--------------------------------

### Implement GetOnigurumaUrl

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

Example implementation of the GetOnigurumaUrl function using fetch and its usage within the createStarryNight options.

```typescript
const getOnigurumaUrl: GetOnigurumaUrl = async () => {
  const response = await fetch('https://cdn.example.com/onig.wasm')
  const blob = await response.blob()
  return new URL(URL.createObjectURL(blob))
}

const starryNight = await createStarryNight(common, {
  getOnigurumaUrlFetch: getOnigurumaUrl
})
```

--------------------------------

### Configure custom WASM loading

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/api-reference.md

Example of providing a custom URL fetcher for the Oniguruma WASM binary in browser environments.

```javascript
// With custom WASM loading in browser
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common, {
  getOnigurumaUrlFetch() {
    return new URL('/wasm/onig.wasm', window.location.href)
  }
})
```

--------------------------------

### Resolve Grammar Scopes

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Examples of using flagToScope to map language names, extensions, or file paths to grammar scopes.

```js
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)

console.log(starryNight.flagToScope('pandoc')) // `'text.md'`
console.log(starryNight.flagToScope('workbook')) // `'text.md'`
console.log(starryNight.flagToScope('.workbook')) // `'text.md'`
console.log(starryNight.flagToScope('path/to/example.js')) // `'source.js'`
console.log(starryNight.flagToScope('whatever')) // `undefined`
```

--------------------------------

### Configure custom WASM host in browser

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

Example of providing a custom URL for the onig.wasm binary in a browser environment using getOnigurumaUrlFetch.

```typescript
const starryNight = await createStarryNight(common, {
  getOnigurumaUrlFetch() {
    return new URL('/static/onig.wasm', window.location.href)
  }
})
```

--------------------------------

### Configure bundled WASM in Node.js

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

Example of resolving a local path for the onig.wasm binary in a Node.js environment using getOnigurumaUrlFs.

```typescript
import fs from 'node:fs'
import path from 'node:path'
import {createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common, {
  getOnigurumaUrlFs() {
    const wasmPath = path.join(process.cwd(), 'public', 'onig.wasm')
    return new URL(wasmPath, import.meta.url)
  }
})
```

--------------------------------

### Register grammars incrementally

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/integration-patterns.md

Allows dynamic registration of additional grammars after initial setup.

```javascript
const starryNight = await createStarryNight([sourceJs])

// Later, when encountering Python code
const sourcePython = await import('@wooorm/starry-night/source.python')
await starryNight.register([sourcePython.default])
```

--------------------------------

### Configure Custom WASM URL in Browser

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

Example of overriding the default WASM fetch URL when initializing Starry-night.

```javascript
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common, {
  getOnigurumaUrlFetch() {
    return new URL('/static/onig.wasm', window.location.href)
  }
})
```

--------------------------------

### Initialize and Highlight Code

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Create a highlighter instance and highlight a string of code.

```javascript
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)
const tree = starryNight.highlight('const x = 1', 'source.js')
console.log(tree)
```

--------------------------------

### Initialize highlighter with specific grammar

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/exports.md

Create a highlighter instance configured with a specific grammar and perform syntax highlighting.

```javascript
import sourceTs from '@wooorm/starry-night/source.ts'
import {createStarryNight} from '@wooorm/starry-night'

// Create highlighter with only TypeScript
const starryNight = await createStarryNight([sourceTs])
const tree = starryNight.highlight('const x: number = 1', 'source.ts')
```

--------------------------------

### Import all grammars

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/textmate-grammars.md

Use the all bundle for comprehensive language support, covering approximately 600 languages.

```javascript
import {all, createStarryNight} from '@wooorm/starry-night'
// Access ~600 grammars
```

--------------------------------

### Initialize Starry Night with Grammar Sets

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Use common or all grammars for initialization. Note that 'all' significantly increases bundle size.

```javascript
import {common, createStarryNight} from '@wooorm/starry-night'
const starryNight = await createStarryNight(common)
```

```javascript
import {all, createStarryNight} from '@wooorm/starry-night'
const starryNight = await createStarryNight(all)
```

--------------------------------

### Example HAST structure

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

A concrete example of a HAST object structure containing span elements and text nodes.

```typescript
{
  type: 'root',
  children: [
    {
      type: 'element',
      tagName: 'span',
      properties: {className: ['pl-s']},
      children: [
        {type: 'text', value: '"'}
      ]
    },
    {type: 'text', value: 'hello'},
    {
      type: 'element',
      tagName: 'span',
      properties: {className: ['pl-s']},
      children: [
        {type: 'text', value: '"'}
      ]
    }
  ]
}
```

--------------------------------

### Initialize with Custom Grammar Selection

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Import specific language grammars individually to minimize bundle size.

```javascript
import sourceCss from '@wooorm/starry-night/source.css'
import sourceJs from '@wooorm/starry-night/source.js'
import {createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight([sourceCss, sourceJs])
```

--------------------------------

### Example Match Rule

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

A simple rule matching numeric digits.

```typescript
{
  match: '[0-9]+',
  name: 'constant.numeric'
}
```

--------------------------------

### Optimize Starry Night initialization

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/integration-patterns.md

Demonstrates caching the starryNight instance to avoid repeated expensive WASM initialization.

```javascript
// DON'T: Create new instance per request
app.post('/highlight', async (req, res) => {
  const starryNight = await createStarryNight(common) // Slow!
  // ...
})

// DO: Create once and reuse
const starryNight = await createStarryNight(common)

app.post('/highlight', (req, res) => {
  const {code, language} = req.body
  const scope = starryNight.flagToScope(language)
  const tree = starryNight.highlight(code, scope)
  // ...
})
```

--------------------------------

### Text Node Example

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/hast-output-format.md

Representation of a text node containing literal content.

```javascript
{
  type: 'text',
  value: ' = '
}
```

--------------------------------

### Element Node Example

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/hast-output-format.md

Representation of a span element node with a keyword class.

```javascript
{
  type: 'element',
  tagName: 'span',
  properties: {className: ['pl-k']},  // Keyword class
  children: [{type: 'text', value: 'const'}]
}
```

--------------------------------

### Initialize Syntax Highlighter

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/exports.md

Factory function to create a syntax highlighter instance.

```javascript
import {createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)
```

--------------------------------

### Create a CLI tool for code highlighting

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/integration-patterns.md

A Node.js script that reads a file from the command line and outputs syntax-highlighted HTML.

```javascript
#!/usr/bin/env node

import {createStarryNight, common} from '@wooorm/starry-night'
import {toHtml} from 'hast-util-to-html'
import fs from 'node:fs/promises'

async function main() {
  const filePath = process.argv[2]
  const language = process.argv[3] || 'javascript'

  const code = await fs.readFile(filePath, 'utf-8')
  const starryNight = await createStarryNight(common)

  const scope = starryNight.flagToScope(language)
  if (!scope) {
    console.error(`Unknown language: ${language}`)
    process.exit(1)
  }

  const tree = starryNight.highlight(code, scope)
  const html = toHtml(tree)

  console.log(html)
}

main().catch(err => {
  console.error(err)
  process.exit(1)
})
```

--------------------------------

### createStarryNight

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Initializes the syntax highlighter with a provided set of grammars and optional configuration for WASM loading.

```APIDOC
## createStarryNight(grammars, options)

### Description
Creates a new starryNight instance using the provided grammar sets. The instance can be configured to load the required WASM file from a custom URL.

### Parameters
- **grammars** (Array<Grammar>) - Required - An array of grammar objects (e.g., `common`, `all`, or custom imports).
- **options** (Object) - Optional - Configuration object for WASM loading.
  - **getOnigurumaUrlFetch** (Function) - Optional - Browser-based function returning a URL for the WASM file.
  - **getOnigurumaUrlFs** (Function) - Optional - Node.js-based function returning a URL for the WASM file.

### Example
```javascript
import {common, createStarryNight} from '@wooorm/starry-night'
const starryNight = await createStarryNight(common, {
  getOnigurumaUrlFetch() {
    return new URL('/wasm/onig.wasm', window.location.href)
  }
})
```
```

--------------------------------

### createStarryNight(grammars, options?)

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/INDEX.md

Creates a new StarryNight instance with the provided grammars and configuration options.

```APIDOC
## createStarryNight(grammars, options?)

### Description
Initializes a new syntax highlighter instance. Returns a Promise that resolves to a StarryNight object.

### Parameters
- **grammars** (Array) - Required - A list of grammars to load.
- **options** (Object) - Optional - Configuration options including WASM loading URLs.
```

--------------------------------

### Verify vscode-oniguruma version

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

Check the installed version of vscode-oniguruma to ensure compatibility with Starry-night v2 requirements.

```bash
npm list vscode-oniguruma
# Should show v2.x.x
```

--------------------------------

### createStarryNight(grammars, options?)

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/api-reference.md

The main factory function used to instantiate a syntax highlighter instance with a provided set of grammars.

```APIDOC
## createStarryNight(grammars, options?)

### Description
Instantiates a syntax highlighter with specified grammars. Returns a Promise that resolves to a StarryNight instance.

### Signature
`async function createStarryNight(grammars: ReadonlyArray<Grammar>, options?: Readonly<Options> | null | undefined): Promise<StarryNight>`

### Parameters
- **grammars** (ReadonlyArray<Grammar>) - Required - Array of grammar objects defining supported languages for highlighting.
- **options** (Readonly<Options> | null | undefined) - Optional - Configuration object for customizing WASM loading behavior.

### Return Type
- **Promise<StarryNight>** - Resolves to a StarryNight instance with methods for highlighting code and managing grammars.

### Throws
- **TypeError** - If internal validation fails during WASM initialization or grammar registration.
- **Error** - If grammar scope resolution fails or WASM binary cannot be loaded.

### Example
```javascript
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)

const scope = starryNight.flagToScope('javascript')
const tree = starryNight.highlight('console.log(1)', scope)
console.log(tree)
```
```

--------------------------------

### Apply Stylesheets in HTML and Bundlers

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/exports.md

Use the 'both' theme for automatic system preference detection in HTML or bundler environments.

```html
<!-- Auto-detection of light/dark mode -->
<link rel="stylesheet" href="https://esm.sh/@wooorm/starry-night@3/style/both">
```

```javascript
// In bundlers
import '@wooorm/starry-night/style/both'
```

--------------------------------

### Highlight Code

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/README.md

Initialize the highlighter with common grammars and highlight a string of code.

```javascript
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)
const scope = starryNight.flagToScope('javascript')
const tree = starryNight.highlight('const x = 1', scope)

console.log(tree)
// {
//   type: 'root',
//   children: [
//     {type: 'element', tagName: 'span', properties: {className: ['pl-k']}, ...}
//   ]
// }
```

--------------------------------

### Example Begin/End Block Rule

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

A rule defining a block enclosed by double quotes with nested escape patterns.

```typescript
{
  begin: '"',
  end: '"',
  name: 'string.quoted.double',
  patterns: [
    {match: '\\.', name: 'constant.character.escape'}
  ]
}
```

--------------------------------

### Handle WASM Loading Errors

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/error-handling-and-edge-cases.md

Shows how to catch WASM initialization failures and implement a fallback mechanism for syntax highlighting.

```javascript
const starryNight = await createStarryNight(common, {
  getOnigurumaUrlFetch() {
    return new URL('/nonexistent/onig.wasm', window.location.href)
  }
})
// Error: 404 Not Found (network error)
```

```javascript
async function createHighlighter() {
  try {
    return await createStarryNight(common, {
      getOnigurumaUrlFetch() {
        return new URL('/wasm/onig.wasm', window.location.href)
      }
    })
  } catch (err) {
    console.error('Failed to initialize highlighter:', err)
    
    // Fallback: no syntax highlighting
    return {
      highlight: (code) => ({
        type: 'root',
        children: [{type: 'text', value: code}]
      })
    }
  }
}
```

--------------------------------

### Markdown Code Block Injection

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/textmate-grammars.md

Example of markdown grammar referencing child grammars for code block highlighting.

```markdown
```javascript
const x = 1
```
```

--------------------------------

### Import common grammars

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/textmate-grammars.md

Use the common bundle for general-purpose code hosting with a manageable bundle size.

```javascript
import {common, createStarryNight} from '@wooorm/starry-night'
// Access 36 grammars with manageable bundle size
```

--------------------------------

### Initialize Starry Night

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

The entry point for creating a Starry Night instance.

```javascript
const starryNight = await createStarryNight(common, options)
```

--------------------------------

### Configure Custom WASM Path in Node.js

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

Example of overriding the default WASM file path when initializing Starry-night in Node.js.

```javascript
import {createStarryNight, common} from '@wooorm/starry-night'
import fs from 'node:fs/promises'
import path from 'node:path'

const starryNight = await createStarryNight(common, {
  async getOnigurumaUrlFs() {
    const wasmPath = path.join(process.cwd(), 'vendor', 'onig.wasm')
    return new URL(wasmPath, import.meta.url)
  }
})
```

--------------------------------

### Import vscode-textmate

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

Usage of the Registry class for grammar parsing.

```javascript
import vscodeTextmate from 'vscode-textmate'

const registry = new vscodeTextmate.Registry({...})
```

--------------------------------

### Automate WASM binary deployment

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

Use npm scripts to copy and checksum the WASM binary, ensuring consistency across environments.

```json
{
  "scripts": {
    "prepare:wasm": "npm run prepare:wasm:copy && npm run prepare:wasm:checksum",
    "prepare:wasm:copy": "cp node_modules/vscode-oniguruma/release/onig.wasm public/onig.wasm",
    "prepare:wasm:checksum": "shasum -a 256 public/onig.wasm > public/onig.wasm.sha256"
  }
}
```

```json
{
  "scripts": {
    "postinstall": "npm run prepare:wasm"
  }
}
```

--------------------------------

### Options Interface

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

Configuration object used as the second parameter in createStarryNight to define custom WASM binary locations.

```APIDOC
## Options Interface

### Description
Configuration object for syntax highlighter initialization. Used to specify custom locations for the Oniguruma WASM binary.

### Fields
- **getOnigurumaUrlFetch** (GetOnigurumaUrl | null | undefined) - Optional - Function or URL returning the location of the WASM binary for regex matching in browsers.
- **getOnigurumaUrlFs** (GetOnigurumaUrl | null | undefined) - Optional - Function or URL returning the location of the WASM binary for Node.js environments.

### Usage
Passed as the second argument to `createStarryNight(grammars, options)`.
```

--------------------------------

### StarryNight Instance Methods

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/INDEX.md

Core methods available on the StarryNight instance for highlighting and grammar management.

```typescript
flagToScope(flag) → string | undefined
highlight(value, scope) → Root
scopes() → Array<string>
missingScopes() → Array<string>
register(grammars) → Promise<undefined>
```

--------------------------------

### Include Built-in Stylesheet

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/README.md

Link the pre-built CSS stylesheet to enable syntax highlighting styles.

```html
<link rel="stylesheet" href="https://esm.sh/@wooorm/starry-night@3/style/both">
```

--------------------------------

### Await Initialization

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/error-handling-and-edge-cases.md

The createStarryNight function returns a Promise. Always await the result before attempting to use the instance.

```javascript
// ❌ WRONG
const starryNight = createStarryNight(common)
const tree = starryNight.highlight('code', 'source.js')
// Error: starryNight is a Promise, not an object

// ✅ RIGHT
const starryNight = await createStarryNight(common)
const tree = starryNight.highlight('code', 'source.js')
```

--------------------------------

### Create Registry

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

Configures the TextMate registry with the initialized Oniguruma WASM module.

```javascript
// In lib/index.js:307
const registry = new vscodeTextmate.Registry({
  async loadGrammar(scopeName) {
    return registered.get(scopeName)
  },
  onigLib: createOniguruma(options)  // WASM module passed here
})

registry.setTheme(theme)

// Load all grammars in parallel
await Promise.all(
  [...registered.keys()].map(scope => registry.loadGrammar(scope))
)
```

--------------------------------

### Apply custom themes with CSS variables

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/integration-patterns.md

Demonstrates browser-side highlighting using CSS variables to define syntax colors.

```html
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    :root {
      --pl-k: #d73a49;      /* Keywords */
      --pl-s: #032f62;      /* Strings */
      --pl-c: #6a737d;      /* Comments */
      --pl-c1: #005cc5;     /* Constants */
      --pl-en: #6f42c1;     /* Entity names */
    }

    code .pl-k { color: var(--pl-k); font-weight: bold; }
    code .pl-s { color: var(--pl-s); }
    code .pl-c { color: var(--pl-c); font-style: italic; }
    code .pl-c1 { color: var(--pl-c1); }
    code .pl-en { color: var(--pl-en); }
  </style>
  <script type="module">
    import {common, createStarryNight} from 'https://esm.sh/@wooorm/starry-night@3?bundle'
    import {toHtml} from 'https://esm.sh/hast-util-to-html@9?bundle'

    const starryNight = await createStarryNight(common)
    const code = 'const x = "hello"'
    const tree = starryNight.highlight(code, 'source.js')
    const html = toHtml(tree)

    document.body.innerHTML = `<pre><code>${html}</code></pre>`
  </script>
</head>
<body></body>
</html>
```

--------------------------------

### StarryNight Methods

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/INDEX.md

Methods available on the StarryNight instance for highlighting and grammar management.

```APIDOC
## StarryNight Methods

### flagToScope(flag)
Converts a language flag (e.g., 'js') to its corresponding scope name.

### highlight(value, scope)
Highlights the provided string value using the specified scope. Returns a HAST Root node.

### scopes()
Returns an array of all currently registered scope names.

### missingScopes()
Returns an array of scopes that are required by loaded grammars but are currently missing.

### register(grammars)
Dynamically registers additional grammars. Returns a Promise that resolves when registration is complete.
```

--------------------------------

### Handle Grammar Dependencies

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/textmate-grammars.md

Demonstrates how to identify and register missing grammar dependencies using missingScopes().

```javascript
import textXmlSvg from '@wooorm/starry-night/text.xml.svg'
import {createStarryNight} from '@wooorm/starry-night'

const svg = await createStarryNight([textXmlSvg])
console.log(svg.missingScopes())  // ['text.xml']

// Register the dependency
import textXml from '@wooorm/starry-night/text.xml'
await svg.register([textXml])

console.log(svg.missingScopes())  // []
```

--------------------------------

### Configure WASM Loading

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/README.md

Initialize the Starry Night instance by providing the path to the Oniguruma WASM file for different environments.

```javascript
const starryNight = await createStarryNight(common, {
  getOnigurumaUrlFetch() {
    return new URL('/wasm/onig.wasm', window.location.href)
  }
})
```

```javascript
const starryNight = await createStarryNight(common, {
  async getOnigurumaUrlFs() {
    return new URL('./onig.wasm', import.meta.url)
  }
})
```

--------------------------------

### Define Options interface

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/types.md

The configuration object structure for initializing the syntax highlighter.

```typescript
interface Options {
  getOnigurumaUrlFetch?: GetOnigurumaUrl | null | undefined
  getOnigurumaUrlFs?: GetOnigurumaUrl | null | undefined
}
```

--------------------------------

### Import individual grammars

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/textmate-grammars.md

Import specific grammars to minimize bundle size by only including the languages required for your application.

```javascript
import sourceJs from '@wooorm/starry-night/source.js'
import sourcePython from '@wooorm/starry-night/source.python'
import {createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight([sourceJs, sourcePython])
```

--------------------------------

### Individual Grammar Imports

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/exports.md

Import specific language grammars to be used with the createStarryNight highlighter instance.

```APIDOC
## Individual Grammar Imports

### Description
Import specific grammars from the package to initialize the highlighter with a subset of supported languages. This helps in reducing the bundle size by only including necessary grammars.

### Import Pattern
`import [name] from '@wooorm/starry-night/[scope]'`

### Parameters
- **[scope]** (string) - The grammar's scope name (e.g., 'source.js', 'text.md'). Dots in the scope name are preserved.

### Usage Example
```javascript
import sourceTs from '@wooorm/starry-night/source.ts'
import {createStarryNight} from '@wooorm/starry-night'

// Create highlighter with only TypeScript
const starryNight = await createStarryNight([sourceTs])
const tree = starryNight.highlight('const x: number = 1', 'source.ts')
```
```

--------------------------------

### Options Interface

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Definition for configuration options.

```typescript
interface Options {
  getOnigurumaUrlFetch?: GetOnigurumaUrl
  getOnigurumaUrlFs?: GetOnigurumaUrl
}
```

--------------------------------

### Highlight from File Path

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/README.md

Resolve a scope from a file path and highlight the code if the scope is found.

```javascript
const scope = starryNight.flagToScope('path/to/file.js')
if (scope) {
  const tree = starryNight.highlight(code, scope)
}
```

--------------------------------

### Load minimal grammars

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Pass only the required language grammars to the initialization function to reduce overhead.

```javascript
const starryNight = await createStarryNight([sourceJs, sourcePython])
```

--------------------------------

### register(grammars)

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Adds more grammars dynamically to the highlighter instance.

```APIDOC
## register(grammars)

### Description
Add more grammars dynamically.

### Signature
`register(grammars: ReadonlyArray<Grammar>): Promise<undefined>`

### Parameters
- **grammars** (ReadonlyArray<Grammar>) - Required - List of grammars to register.
```

--------------------------------

### Highlight code in Node.js

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/integration-patterns.md

Basic implementation using the common grammar set and hast-util-to-html for output.

```javascript
import {common, createStarryNight} from '@wooorm/starry-night'
import {toHtml} from 'hast-util-to-html'

const starryNight = await createStarryNight(common)

const scope = starryNight.flagToScope('javascript')
const tree = starryNight.highlight('console.log(1)', scope)
const html = toHtml(tree)

console.log(html)
// Output: <span class="pl-en">console</span>.<span class="pl-c1">log</span>(<span class="pl-c1">1</span>)
```

--------------------------------

### Load WASM with vscode-oniguruma

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

Initializes the regex engine wrapper.

```javascript
import vscodeOniguruma from 'vscode-oniguruma'

await vscodeOniguruma.loadWASM(wasmBinary)
```

--------------------------------

### Create Custom Grammar

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/textmate-grammars.md

Shows how to define a custom Grammar object and register it with starry-night.

```javascript
import {createStarryNight} from '@wooorm/starry-night'

const customGrammar = {
  scopeName: 'source.custom',
  names: ['custom', 'custom-lang'],
  extensions: ['.custom', '.customlang'],
  patterns: [
    {
      match: '\\b(if|else|while)\\b',
      name: 'keyword'
    },
    {
      begin: '"',
      end: '"',
      name: 'string.quoted.double'
    }
  ]
}

const starryNight = await createStarryNight([customGrammar])
const tree = starryNight.highlight('if x > 0', 'source.custom')
```

--------------------------------

### CSS Stylesheets

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Methods for importing CSS themes for syntax highlighting.

```APIDOC
## CSS Stylesheets

### HTML Link
```html
<link rel="stylesheet" href="https://esm.sh/@wooorm/starry-night@3/style/both">
```

### Bundler Import
```javascript
import '@wooorm/starry-night/style/both'
```
```

--------------------------------

### Client-side syntax highlighting

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Shows how to run Starry Night in the browser to dynamically highlight code blocks using hast-util-to-dom.

```js
import {
  common,
  createStarryNight
} from 'https://esm.sh/@wooorm/starry-night@3?bundle'
import {toDom} from 'https://esm.sh/hast-util-to-dom@4?bundle'

const starryNight = await createStarryNight(common)
const prefix = 'language-'

const nodes = Array.from(document.body.querySelectorAll('code'))

for (const node of nodes) {
  const className = Array.from(node.classList).find(function (d) {
    return d.startsWith(prefix)
  })
  if (!className) continue
  const scope = starryNight.flagToScope(className.slice(prefix.length))
  if (!scope) continue
  const tree = starryNight.highlight(node.textContent, scope)
  node.replaceChildren(toDom(tree, {fragment: true}))
}
```

```html
<!doctype html>
<meta charset=utf8>
<title>Hello</title>
<link rel=stylesheet href=https://esm.sh/@wooorm/starry-night@3/style/both>
<body>
<h1>Hello</h1>
<p>…world!</p>
<pre><code class=language-js>console.log('it works!')
</code></pre>
<script type=module src=./example.js></script>
</body>
```

```html
<code class="language-js"><span class="pl-en">console</span>.<span class="pl-c1">log</span>(<span class="pl-s"><span class="pl-pds">'</span>it works!<span class="pl-pds">'</span></span>)
</code>
```

--------------------------------

### Handle Highlighting Errors in JavaScript

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/integration-patterns.md

Use a try-catch block to manage initialization and highlighting failures, including checks for unsupported language scopes.

```javascript
import {createStarryNight, common} from '@wooorm/starry-night'

try {
  const starryNight = await createStarryNight(common)
  
  const scope = starryNight.flagToScope('unknown-lang')
  if (!scope) {
    console.warn('Language not supported')
    return plainText
  }

  const tree = starryNight.highlight(code, scope)
  return toHtml(tree)
} catch (err) {
  console.error('Highlighting failed:', err)
  return plainText
}
```

--------------------------------

### Implement line numbers and line highlighting

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/integration-patterns.md

Wraps highlighted code in custom HTML structures to support line numbering and specific line highlighting.

```javascript
import {common, createStarryNight} from '@wooorm/starry-night'
import {toHtml} from 'hast-util-to-html'

async function highlightWithLineNumbers(code, language, highlightLines = []) {
  const starryNight = await createStarryNight(common)
  const scope = starryNight.flagToScope(language)

  const lines = code.split('\n')
  const highlightedLines = lines.map((line, index) => {
    const lineNum = index + 1
    const tree = starryNight.highlight(line, scope)
    const html = toHtml(tree)
    const isHighlighted = highlightLines.includes(lineNum)
    
    return `
      <div class="line ${isHighlighted ? 'highlight' : ''}">
        <span class="line-number">${lineNum}</span>
        <span class="line-code">${html}</span>
      </div>
    `
  })

  return `<div class="highlighted-code">${highlightedLines.join('')}</div>`
}

// Usage
const code = 'const x = 1\nconst y = 2\nconst z = 3'
const html = await highlightWithLineNumbers(code, 'javascript', [2])
console.log(html)
```

--------------------------------

### Include CSS Stylesheets

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Load themes via HTML link tags or JavaScript imports in bundlers.

```html
<!-- Auto light/dark mode -->
<link rel="stylesheet" href="https://esm.sh/@wooorm/starry-night@3/style/both">

<!-- Light theme only -->
<link rel="stylesheet" href="https://esm.sh/@wooorm/starry-night@3/style/light">

<!-- Dark theme only -->
<link rel="stylesheet" href="https://esm.sh/@wooorm/starry-night@3/style/dark">
```

```javascript
import '@wooorm/starry-night/style/both'
```

--------------------------------

### CSS Style Exports

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/exports.md

Import CSS stylesheets to apply GitHub's PrettyLights color schemes. Themes include 'both' (auto-detect), 'dark', and 'light'.

```APIDOC
## CSS Style Imports

### Description
Import CSS stylesheets from the `@wooorm/starry-night/style/` export map to apply syntax highlighting themes.

### Available Themes
- **both**: Light and dark mode (auto-detects system preference)
- **dark**: Dark color scheme
- **light**: Light color scheme

### Usage Example
```typescript
import '@wooorm/starry-night/style/both'
```
```

--------------------------------

### Use All Grammars

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/exports.md

Usage of the full grammar set, which includes approximately 600 languages.

```javascript
import {all, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(all)
// Can highlight ~600 languages
```

--------------------------------

### Optimize Instance Creation

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/error-handling-and-edge-cases.md

Avoid creating multiple instances of Starry Night to prevent redundant WASM loading. Initialize once and reuse the instance.

```javascript
// ❌ SLOW (WASM loaded multiple times)
for (let i = 0; i < 100; i++) {
  const sn = await createStarryNight(common)
  highlight(sn, code)
}

// ✅ FAST (WASM loaded once)
const starryNight = await createStarryNight(common)
for (let i = 0; i < 100; i++) {
  highlight(starryNight, code)
}
```

--------------------------------

### Load grammars dynamically

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/integration-patterns.md

Reduces bundle size by importing specific language grammars only when needed.

```javascript
import {createStarryNight} from '@wooorm/starry-night'

async function getHighlighter(language) {
  // Dynamically import grammar based on language
  const grammarModule = await import(`@wooorm/starry-night/source.${language}`)
  const grammar = grammarModule.default

  const starryNight = await createStarryNight([grammar])
  return starryNight
}

// Usage
const jsHighlighter = await getHighlighter('js')
const pythonHighlighter = await getHighlighter('python')
```

--------------------------------

### Resolve Module Paths

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/wasm-and-dependencies.md

Uses import-meta-resolve to locate the WASM binary in Node.js environments.

```javascript
import {resolve} from 'import-meta-resolve'

const onigUrl = resolve('vscode-oniguruma', import.meta.url)
```

--------------------------------

### Check Language Support

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Verifies if a specific language is supported before attempting to highlight.

```javascript
function isLanguageSupported(language) {
  return starryNight.flagToScope(language) !== undefined
}

if (!isLanguageSupported(userLanguage)) {
  console.warn(`${userLanguage} not supported`)
}
```

--------------------------------

### highlight(value, scope)

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/api-reference.md

Tokenizes source code and returns a HAST AST with syntax highlighting classes.

```APIDOC
## highlight(value, scope)

### Description
Tokenizes the provided source code string and returns a HAST AST structure with syntax highlighting classes.

### Parameters
- **value** (string) - Required - The source code to highlight.
- **scope** (string) - Required - The registered grammar scope to use for tokenization.

### Return Type
- **Root** - HAST root node representing the highlighted code.

### Throws
- **TypeError** - If value or scope is not a string.
- **Error** - If scope is not a registered grammar.
```

--------------------------------

### starryNight.scopes()

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Lists all currently registered grammar scopes.

```APIDOC
## starryNight.scopes()

### Description
Returns a list of all grammar scopes that are currently registered and available for highlighting.

### Returns
- **Array<string>** - A list of registered grammar scope identifiers.
```

--------------------------------

### Import Options Type

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/exports.md

Import the configuration options interface for type checking.

```typescript
import type {Options} from '@wooorm/starry-night'
```

--------------------------------

### Output Serialization

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Methods for converting syntax-highlighted trees into HTML strings, JSX elements, or DOM nodes.

```APIDOC
## Serialization Methods

### To HTML
```javascript
import {toHtml} from 'hast-util-to-html'
const html = toHtml(tree)
```

### To JSX/React
```javascript
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'react/jsx-runtime'
const element = toJsxRuntime(tree, {Fragment, jsx, jsxs})
```

### To DOM
```javascript
import {toDom} from 'hast-util-to-dom'
const domNode = toDom(tree)
document.body.appendChild(domNode)
```
```

--------------------------------

### Test syntax highlighting and scope mapping

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/integration-patterns.md

Uses the ava test runner to verify highlight output and language flag resolution.

```javascript
import test from 'ava'
import {createStarryNight, common} from '@wooorm/starry-night'
import {toHtml} from 'hast-util-to-html'

test('highlight JavaScript correctly', async t => {
  const starryNight = await createStarryNight(common)
  const tree = starryNight.highlight('const x = 1', 'source.js')
  const html = toHtml(tree)

  t.true(html.includes('pl-k'))  // Keyword class
  t.true(html.includes('pl-c1')) // Constant class
  t.true(html.includes('const'))
  t.true(html.includes('1'))
})

test('flagToScope matches languages', async t => {
  const starryNight = await createStarryNight(common)

  t.is(starryNight.flagToScope('js'), 'source.js')
  t.is(starryNight.flagToScope('javascript'), 'source.js')
  t.is(starryNight.flagToScope('.js'), 'source.js')
  t.is(starryNight.flagToScope('unknown'), undefined)
})
```

--------------------------------

### Convert HAST to React nodes

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Illustrates transforming a highlighted HAST tree into React nodes using hast-util-to-jsx-runtime.

```js
import {common, createStarryNight} from '@wooorm/starry-night'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'react/jsx-runtime'

const starryNight = await createStarryNight(common)

const tree = starryNight.highlight('"use strict";', 'source.js')
const reactNode = toJsxRuntime(tree, {Fragment, jsx, jsxs})

console.log(reactNode)
```

```js
{
  '$$typeof': Symbol(react.element),
  type: Symbol(react.fragment),
  key: null,
  ref: null,
  props: { children: [ [Object], ';' ] },
  _owner: null,
  _store: {}
}
```

--------------------------------

### Handle Unregistered Grammar Scopes

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/error-handling-and-edge-cases.md

Illustrates the error caused by using an unregistered scope and demonstrates how to check for and register missing grammars dynamically.

```javascript
const starryNight = await createStarryNight(common)

// Try highlighting with a scope that's not registered
starryNight.highlight('code', 'source.unknown')
// Error: Expected grammar `source.unknown` to be registered
```

```javascript
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common)

// Check available scopes first
const allScopes = starryNight.scopes()
console.log(allScopes.includes('source.rust'))  // true or false

if (!allScopes.includes('source.rust')) {
  // Register the missing grammar
  const sourceRust = await import('@wooorm/starry-night/source.rust')
  await starryNight.register([sourceRust.default])
}

const tree = starryNight.highlight('fn main() {}', 'source.rust')
```

--------------------------------

### Reuse Starry Night instance

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Initialize the instance once and reuse it for multiple highlighting operations to improve performance.

```javascript
const starryNight = await createStarryNight(common)
// Reuse for all highlights
```

--------------------------------

### Highlight from File Path

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Detects the language scope based on a file path and highlights the provided code content.

```javascript
import path from 'node:path'

function highlightFile(filePath, code) {
  const scope = starryNight.flagToScope(filePath)
  
  if (!scope) {
    console.warn(`Unknown file type: ${filePath}`)
    return null
  }
  
  return starryNight.highlight(code, scope)
}
```

--------------------------------

### Configure Oniguruma URL

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Provides a custom URL for the Oniguruma WASM binary during initialization. Ensure the binary version matches the internal dependency requirements.

```js
import {common, createStarryNight} from '@wooorm/starry-night'

const starryNight = await createStarryNight(common, {
  getOnigurumaUrlFetch() {
    return new URL('/onig.wasm', window.location.href);
  }
})
```

--------------------------------

### Import Grammars and Styles

Source: https://github.com/wooorm/starry-night/blob/main/readme.md

Importing specific grammars and CSS styles using the package's export map.

```js
import sourceMdx from '@wooorm/starry-night/source.mdx' // Grammar.
import styleTritanopiaDark from '@wooorm/starry-night/style/tritanopia-dark' // CSS.
```

--------------------------------

### Import Grammar Type

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/exports.md

Import the TextMate grammar interface for type checking.

```typescript
import type {Grammar} from '@wooorm/starry-night'
```

--------------------------------

### Map Flags to Scopes

Source: https://github.com/wooorm/starry-night/blob/main/_autodocs/quick-reference.md

Map language names, extensions, or file paths to grammar scopes.

```typescript
flagToScope(flag: string): string | undefined
```

```javascript
starryNight.flagToScope('javascript')       // → 'source.js'
starryNight.flagToScope('.js')              // → 'source.js'
starryNight.flagToScope('path/to/file.js')  // → 'source.js'
starryNight.flagToScope('unknown')          // → undefined
```
Tokens:
Raw