📷 Ka-chick

Using Kachik, you can easily create a self-hosted service for taking screenshots from pages. Powered by Playwright and Headless Chromium.

Ka-chick is read like "click" the sound taking a picture also is a village in Golestan, Iran.

Features

✅ Simple http and programmatic interfaces.

✅ Custom document selector and masks for taking screenshot.

✅ Strong cache support powered by unjs/unstorage.

✅ Remote URL and inline HMTL rendering

Warning Is is an experimental project. Do not use for production yet!

CLI Usage

$ npx kachik@latest

ℹ Kachik x.y.z
ℹ Cache directory: /.cache/kachik
  > Local:    http://localhost:3000/

Open this sample URL: http://localhost:3000/kachik/dark,s:.VPHome,m:.VPNav%2C.actions/https://vitejs.dev/

What it does:

• Open a chromium browser
• Navigates to https://vitejs.dev/
• Emulated dark theme
• Removes action buttons using .VPNav>.actions query selector
• Uses .VPHome query selector to take a screenshot
• Stores screenshot in cache for future requests and avoid rerendering

API

API is powered by unjs/h3.

/capture/:options/:url

Use this URL to take a screenshot of page. options are optional pairs seperated by , and :/= for value.

Possible options:

• dark: Sets colorScheme to dark.
• s: Document query selector. Default is body.
• m: Query selector of masks to hide using display: none;

When you have no options, use _ in place. Example: https://mydomain/kachik/_/https://google.com.

Inline HTML

URL can be also an inline html. You need to prefix it with html: and ensure it is url encoded.

Example: http://localhost:3000/kachik/_/html:%3Ch1%20style=%22color:blue;display:flex;align-items:center%22%3EHelo%20World

/

When making a request to / endpoint, reponse is a JSON object showing kachik version of resource usage.

Programmatic Usage

Install library

# npm
npm install kachik

# yarn
yarn install kachik

# pnpm
pnpm install kachik

Kachik Instance

Instance of kachik is a lazy context that can be used to invoke other APIs:

import { createKachik } from 'kachik'
// const { createKachik } = require('kachik')

const kachik = createKachik({ options })

Options:

• storage: Custom unjs/unstorage instance for caching.
• browser: Either chromium, firefox or webkit. Default is chromium.
• cacheDir: Filesystem cache directory. Default is .cache/kachik. Can be set to false to use in-memory cache. (Warning: In memory is currently infinity!)

kachik.screenshot(url, options?)

Using kachik.screenshot you can request to take a screenshot of a page:

import { writeFile } from 'node:fs/promises'

const buffer = await kachik.screenshot('http://google.com', { colorScheme: 'dark' })
await writeFile(buffer, 'screenshot.png')

Options:

• colorScheme: (Optional) Emulates browser color scheme.
• selector: (Optional) A valid query selector from the part of the page. Default is body.
• mask: (Optional) A valid query selector to remove from page using display: none;

kachik.close()

When you had no use of kachik anymore, call close() to free up resources and memory.

// Dispose kachik resources
await kachik.close()

💻 Development

• Clone this repository
• Enable Corepack using corepack enable (use npm i -g corepack for Node.js < 16.10)
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

Made with 💛

Published under MIT License.