thuongtruong1009/flashot-api

By thuongtruong1009

•Updated 8 months ago

📟 Rapidly snapshot code snippets as images

Image

Languages & frameworks

API management

Developer tools

384

Overview Tags

thuongtruong1009/flashot-api repository overview

Flashot is the blazing-fast image generation tool for code snippets with elegant design and flawless performance

Super fast: (generated in ~135ms)

⁠✨ Features

🖥️ Used from CLI: Use Flashot as a command-line tool for quick image generation
📥 Used from import: Use Flashot as an importable module in your code:
- 👩‍💻 Inline code support: Easily convert inline code snippets to images
- 🌐 URL support: Fetch code snippets directly from URLs
- 🗂️ File path support: Convert code snippets from local files
- 🗃️ Buffer support: Convert code snippets from buffers
🎨 Customizable styles: Choose from various options to match your style
📦 Lightweight: Minimal dependencies to keep your project lean
📏 Line numbers: Support for displaying & customizing line numbers
🖍️ Highlighting: Support for custom syntax highlighting
🗄️ Render caching: Efficiently handles caching for improved performance (render, tokens, sizes, fonts)
🪓 Multi-format support: Generate images in various formats (png, jpeg, webp, avif)
🖼️ High-quality output: Generates crisp and clear images which keep the original code's formatting intact
⚡ Blazing fast: Optimized for speed, ensuring quick image generation
🛠️ Easy to use: Easy to integrate into your projects with a simple API
🔷 TypeScript support: Fully typed for better developer experience
🔍 Extensive testing: Thoroughly tested with a comprehensive suite of unit tests
🔋 Easy integration: Simple API for seamless integration into your projects
🔧 Flexible environment support: Works seamlessly in various environments (Node.js, Bun, Deno, Workers, …)

⁠📦 Installation

⁠⚙️ For API usage, install via your favorite package manager:

npm install flashot

yarn add flashot

pnpm add flashot

bun install flashot

deno add jsr:@thuongtruong109/flashot

npx jsr add @thuongtruong/flashot

⁠🛠 For CLI usage, install globally via npm:

npm install -g flashot

Then quick check from terminal with CLI runner

flashot -h

⁠🪔 Usage Example

⁠⚙️ For API usage, you can import the functions from the package:

⁠Inline code

import { writeFile } from "node:fs/promises";
import { codeToImg } from "flashot";

const buffer = await codeToImg('console.log("hello, world!");', {
  /* add more options*/
});
await writeFile("inline.webp", buffer);

⁠Raw content url

import { writeFile } from "node:fs/promises";
import { urlToImg } from "flashot";

const buffer = await urlToImg("https://randomfox.ca/floof", {
  /* add more options*/
  format: OutputFormat.Png,
});
await writeFile("url.png", buffer);

⁠Buffer

import { writeFile } from "node:fs/promises";
import { bufferToImg } from "flashot";

const buffer =
  "<Buffer 54 68 69 73 20 69 73 20 61 20 62 75 66 66 65 72 20 65 78 61 6d 70 6c 65 2e>";
const img = await bufferToImg(buffer, {
  /* add more options*/
});
await writeFile("buffer.png", img);

⁠Path dir

import { writeFile } from "node:fs/promises";
import { pathToImg } from "flashot";

const img = await pathToImg("../package.json", {
  /* add more options*/
});
await writeFile("path.png", img);

⁠🛠 For CLI usage, you can run the commands from your terminal:

⁠Inline code

flashot code "console.log('Hello world')" <...options>

⁠Raw content url

flashot url "https://randomfox.ca/floof" <...options>

⁠Buffer

flashot buffer "<Buffer 54 68 69 73 20 69 73 20 61 20 62 75 66 66 65 72 20 65 78 61 6d 70 6c 65 2e>" <...options>

⁠Path dir

flashot path "../package.json" <...options>

⁠Options

⁠🛠 CLI️ options

Usage: flashot [command] [options]

Commands:
  code <code>                           Convert code string to image
  file <file>                           Convert code file to image
  url <url>                             Convert code from URL to image
  buffer <buffer>                       Convert hex buffer string to image
  help [command]                        display help for command

Options:
  -V, --version                         output the version number
  -o, --output <file>                   output image file path (default: "tmp.webp")
  -l, --lang <language>                 programming language (default: "js")
  -t, --theme <theme>                   syntax highlighting theme (default: "dracula")
  -f, --font <font>                     font family to use (default: "https://fonts.bunny.net/jetbrains-mono/files/jetbrains-mono-latin-400-normal.woff2")
  --format <format>                     output image format (png, jpeg, webp, avif) (default: "webp")
  -q, --quality <percent>               image quality (1-100) (only for jpeg) (default: "100")
  -g, --gap <pixels>                    gap between lines (default: "1")
  -p, --style-padding <pixels>          padding around code (default: "25")
  --style-border-radius <pixels>        border radius (default: "8")
  -b, --bg <color>                      background color (default: "not needed!")
  -w, --width <pixels>                  image width (default: "not needed!")
  -H, --height <pixels>                     image height (default: "not needed!")
  -L, --line-numbers-enabled                enable line numbers (default: false)
  --line-numbers-start-from <number>    line number start (default: "1")
  --line-numbers-color <color>          line number color (default: "#7b7f8b")
  --line-numbers-margin-right <pixels>  line number margin right (default: "0")
  --highlight-enabled                   enable line highlighting (default: false)
  --highlight-background-color <color>  highlight background color (default: "#347faa23")
  --highlight-border-radius <pixels>    highlight border radius (default: "0")
  --highlight-at <line>                 highlight line number (default: "1")
  --highlight-depth <number>            highlight depth (shadow effect) (default: "1")
  -v, --verbose                         enable verbose output
  -h, --help                            display help for command

⁠⚙️ API options (default is not needed)

const defaultOptions = {
  lang: "ts", // default is javascript
  theme: "ayu-dark", // default is github-dark
  font: "https://fonts.bunny.net/ubuntu-sans-mono/files/ubuntu-sans-mono-latin-400-normal.woff2", // default is bunny.net/jetbrains-mono.
  format: "png", // default is "webp" (options: png, jpeg, webp, avif)
  quality: 100, // default is 100 (1-100), only applies to jpeg formats
  width: 800, // default is system's width
  height: 400, // default is system's height
  bg: "transparent", // default is system's background
  gap: 1, // gap between lines (default is 1)
  style: {
    borderRadius: 10, // default is 8
    padding: 30, // default is 25
    // ... more custom styles
  },
  lineNumbers: {
    enabled: true, // default is false
    startFrom: 5, // default is 1
    color: "#d64141ff", // default is #7b7f8b
    marginRight: 2, // default is 0
  },
  highlight: {
    enabled: true, // default is false
    backgroundColor: "#25ce5da1", // default is #347faa23,
    borderRadius: 2, // default is 0
    at: 2, // start from at line - default is 1
    depth: 3, // total lines - default is 1
  },
};

Option	Description	Default
`lang`	Code language (supported⁠)	`"js"`
`theme`	Rendering theme (supported⁠)	`"github-dark"`
`font`	Font for rendering (URL/Buffer/ArrayBuffer)	`Jetbrains Mono`⁠
`format`	Output image format (`png`, `jpeg`, `webp`, `avif`)	`webp`
`quality`	Image quality (1-100) for JPEG formats	`100`
`width`	Image width	System default
`height`	Image height	System default
`bg`	Background color	Theme's background
`gap`	Gap between lines	`1`
`style`	Additional container styles (docs⁠)	`{ borderRadius: 8, padding: 25 }`
`lineNumbers`	Line number styles	`{ enabled: false, color: '#7b7f8b', marginRight: 0 }`
`highlight`	Syntax highlighting styles	`{ enabled: false, backgroundColor: '#347faa23', borderRadius: 0, at: 1, depth: 1 }`

⁠🧪 Code Coverage

File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
All files	99.17	81.25	100	99.17
core.ts	100	100	100	100
index.ts	100	100	100	100
shared.ts	100	100	100	100
utils.ts	98.36	78.57	100	98.36	67

Coverage

⁠🏁 Benchmarks

No	Task name	Latency avg (ns)	Latency med (ns)	Throughput avg (ops/s)	Throughput med (ops/s)	Samples
1	1 lines	10175455 ± 1.43%	10075900 ± 106800	99 ± 1.05%	99 ± 1	99
2	10 lines	39056303 ± 0.45%	38845500 ± 405750	26 ± 0.44%	26 ± 0	64
3	100 lines	343126433 ± 0.29%	343616650 ± 2711850	3 ± 0.29%	3 ± 0	64
4	1000 lines	1726190939 ± 0.46%	1715535300 ± 13138650	1 ± 0.45%	1 ± 0	64

⁠� Docker Deployment

Flashot API is available as Docker images on both GitHub Container Registry and Docker Hub.

⁠Quick Start with Docker

# Pull from GitHub Container Registry
docker pull ghcr.io/thuongtruong109/flashot-api:latest

# Or pull from Docker Hub
docker pull thuongtruong109/flashot-api:latest

# Run the container
docker run -p 8080:8080 ghcr.io/thuongtruong109/flashot-api:latest

⁠Docker Compose

# Clone the repository
git clone https://github.com/thuongtruong109/flashot.git
cd flashot

# Start with Docker Compose
docker-compose up -d

⁠Container Registries

GitHub Container Registry: ghcr.io/thuongtruong109/flashot-api
Docker Hub: thuongtruong109/flashot-api

⁠Available Tags

latest - Latest stable release
main - Latest development build
main-<sha> - Specific commit builds

⁠API Endpoints

Once running, the API provides several endpoints:

POST / - Convert code string to image
POST /url - Convert code from URL to image
POST /file - Convert code from file path to image
POST /buffer - Convert code from hex buffer to image
GET /options - Get available configuration options
GET /health - Health check endpoint

Example usage:

curl -X POST http://localhost:8080/ \
  -H "Content-Type: application/json" \
  -d '{
    "code": "console.log(\"Hello, World!\");",
    "options": {
      "lang": "javascript",
      "theme": "github-dark",
      "format": "png"
    }
  }' \
  --output hello-world.png

For detailed deployment instructions, see api/DEPLOYMENT.md⁠.

⁠�📚 Technologies

⚡ Bun⁠ - Fast all-in-one JavaScript runtime and toolkit
🏗️ TypeScript⁠ - Type-safe development with strict mode enabled
📦 Vite⁠ - Lightning-fast build tool with optimized bundling
🪓 Tsdown⁠ - A powerful tool for TypeScript package
🧪 Vitest⁠ - Blazing fast unit testing & interactive test UI framework
🎨 Shiki⁠ and Takumi⁠ - Render container highlight
📝 Biome⁠ - Fast formatter and linter for consistent code style
🚀 Dual Module Support - ESM and CommonJS output with proper type definitions
🔥 ESLint⁠ - Advanced linting with TypeScript and SonarJS rules
🧩 Lefthook⁠ and Commitlint⁠ - Automated Git hooks for linting and formatting
🛠️ Tinybench⁠ - A tiny benchmarking library for measuring performance
🖥️ Commander⁠ - A popular library for building command-line interfaces

⁠🤝 Contributing

Contributions are welcome! This starter kit uses:

Automated code formatting and linting
Comprehensive test coverage requirements

Please ensure all tests pass and code quality checks succeed before submitting a PR.

Check CONTRIBUTING.md⁠ for more information.

⁠💬 Discussions

Head over to the discussions⁠ to share your ideas.

⁠📄 License

MIT License⁠ - Tran Nguyen Thuong Truong⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:9ca294cd6…

Size

100.9 MB

Last updated

8 months ago

docker pull thuongtruong1009/flashot-api