Sandros94 LAB

A personal collection of Nuxt and Nitro tools. The goal of this project is mainly to simplify my prototyping process and learn a few things about data manipulation, Vitest, CI and others in a laboratory-like environment.

• ✨  Release Notes

Features

• useMem: integrates an in-memory kv store, build on-top of unstorage and editable via runtimeConfig (server-only).
• useFS: integrates a filesystem storage, build on-top of unstorage and editable via runtimeConfig (server-only).
• useS3 (optional): integrates any S3 compatible storage, build on-top of unstorage and editable via runtimeConfig (server-only).
• useKV (optional): integrates any Redis compatible KV stores, build on-top of unstorage and editable via runtimeConfig (server-only).
• useZlib (optional): when enabled, it automatically provides gzip compression and decompression functions to useMem, useFS and useKV (server-only).
• Built-in validation (optional): using valibot and h3-valibot under the hood (client and server).

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add @sandros94/lab

To enable or disable various features you can simply edit your nuxt.config.ts like so:

export default defineNuxtConfig({
  modules: ['@sandros94/lab'],

  lab: {
    cache: 'kv',  // 'mem', 'fs', 'kv' or null (default)
    s3: true,     // default false
    kv: true,     // default false
    zlib: true,   // default false
    valibot: true // default false
    cms: true     // default false
  }
})

lab.mem, lab.kv and lab.zlib also accept an object to edit their defaults options.

export default defineNuxtConfig({
  modules: ['@sandros94/lab'],

  lab: {
    mem: {
      ttl: 10 * 60,
    },
    fs: {
      base: '.data/myStore', // Default '.data/lab'
    },
    s3: {
      endpoint: 'https://example.com',
      region: 'us-east-1',
      bucket: 'myBucket',
      accessKeyId: '<your-access-key>',      // Best to use env vars
      secretAccessKey: '<your-secret-key>',  // Best to use env vars
    },
    kv: {
      ttl: 10 * 60,
    },
    cms: {
      addRoutes: true, // default true
    }
  }
})

You can also edit them via env vars: NUXT_LAB_{MEM|FS|S3|KV|ZLIB}_*. Useful in situations like editing NUXT_LAB_KV_URL at runtime without rebuilding the application.

Utils

The @sandros94/lab module includes some utility functions:

useMem

Based on unstorage is a custom in-memory driver. It provides added functionality like time-based metadata, optional size calculation and TTL support with auto-purge.

const mem = useMem()

mem.setItem('key', 'value', { ttl: 60 }) // Expires in 60 seconds

const meta = mem.getMeta('key') // { ttl, atime, mtime, ctime, birthtime, size, timeoutId }

When combined with zlib it also receives the following functions:

• setGzip: Compresses data using gzip and stores it in the KV store.
• getGzip: Retrieves compressed data from the KV store without decompressing it.
• getGunzip: Retrieves compressed data from the KV store, decompresses it, and returns the original data.

useFS

Based on useStorage and usestorage's fs driver, to provide runtime-editable support for storing data on the filesystem. It can also be combiled with zlib to provide gzip support as described above (by default a .gz suffix is added to the key).

[NOTE] By default data is stored under .data/lab in the project root. You can change this by setting lab.fs.base in your nuxt.config.ts.

useS3 (optional)

Based on useStorage and usestorage's s3 driver, to provide runtime-editable support with any S3 compatible storages. It can also be combiled with zlib to provide gzip support as described above (by default a .gz suffix is added to the key).

useKV (optional)

Based on useStorage and usestorage's redis driver, to provide runtime-editable support with any Redis compatible KV stores. It can also be combiled with zlib to provide gzip support as described above.

useZlib (optional)

Mainly used internally for useKV, it currently only provides the following functions:

• gzip: Compresses data using gzip.
• gunzip: Decompresses gzip-compressed data.

cache (optional)

There is built-in support to use useMem or useKV as a cache provider. You can switch between them by setting lab.cache to either 'mem' or 'kv' or disable it via null (default). This automatically configures Nuxt and Nitro for caching server-side requests and functions.

CMS (optional)

This is a highly experimental feature. Much like Nuxt Content it allows to load static content from a directory in your project (cms by default) and serve it via server util and api routes. The content will be bundled at build time and served both as JSON object (if the format is supported for conversion) and served as is, if the file extension is added in the request.

Supported formats:

• .json
• .yaml (.yml)
• .toml (.tml)
• .md (.mdc)

[!NOTE] While markdown is supported and parsed via @nuxtjs/mdc under the hood, if you are looking for a proper markdown-based CMS, you should use Nuxt Content instead.

Start by creating a cms directory in your project root and adding some content files.

# cms/hello.yaml
title: Hello World
content: |
  This is a test content.

By default it will be served at /_cms/hello as JSON, but you can also access it as /_cms/hello.yaml to get the raw content.

If you want more control, you can disable the built-in routes via lab.cms.addRoutes: false (in your nuxt.config.ts) and create your own routes:

export default defineEventHandler(async (event) => {
  const slug = getRouterParam(event, 'slug') || 'index'
  const data = await queryStaticContent(slug)

  if (!data) {
    throw createError({
      status: 404,
      message: 'Not found',
    })
  }

  return data
})

Contribution

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

License

Published under the MIT license.