@nuxthub/core
Version:
Build full-stack Nuxt applications on Cloudflare, with zero configuration.
633 lines (625 loc) • 18.6 kB
text/typescript
import * as _nuxt_schema from '@nuxt/schema';
import { R2HTTPMetadata, ReadableStream, D1Database as D1Database$1, Vectorize as Vectorize$1 } from '@cloudflare/workers-types/experimental';
import { MimeType } from '@uploadthing/mime-types';
import { Storage } from 'unstorage';
interface ModuleHooks {
/**
* Add directories to the database migrations.
* @param dirs - The path of the migrations directories to add.
* @returns void | Promise<void>
*/
'hub:database:migrations:dirs': (dirs: string[]) => void | Promise<void>;
/**
* Add queries to run after the database migrations are applied but are not tracked in the _hub_migrations table.
* @param queries - The path of the SQL queries paths to add.
* @returns void | Promise<void>
*/
'hub:database:queries:paths': (queries: string[]) => void | Promise<void>;
}
interface ModuleOptions {
/**
* Set `true` if the project type is Workers.
*
* If `nitro.experimental.websocket` is enabled, the preset will be set to `cloudflare_durable`, otherwise the preset will be `cloudflare_module`.
*
* @default false
*/
workers?: boolean;
/**
* Set `true` to enable AI for the project.
*
* Requires running `npx nuxthub link` for local development.
*
* @default false
* @see https://hub.nuxt.com/docs/features/ai
* @see https://hub.nuxt.com/docs/features/autorag
*/
ai?: boolean;
/**
* Set `true` to enable the analytics for the project.
*
* @default false
*/
analytics?: boolean;
/**
* Set `true` to enable the Blob storage for the project.
*
* @default false
* @see https://hub.nuxt.com/docs/features/blob
*/
blob?: boolean;
/**
* Set `true` to enable the Browser rendering for the project.
*
* @default false
* @see https://hub.nuxt.com/docs/features/browser
*/
browser?: boolean;
/**
* Set `true` to enable caching for the project.
*
* @default false
* @see https://hub.nuxt.com/docs/features/cache
*/
cache?: boolean;
/**
* Set `true` to enable the database for the project.
*
* @default false
* @see https://hub.nuxt.com/docs/features/database
*/
database?: boolean;
/**
* Set `true` to enable the Key-Value storage for the project.
*
* @default false
* @see https://hub.nuxt.com/docs/features/kv
*/
kv?: boolean;
/**
* Set Vectorize indexes for the project.
*
* Currently there is a limit of 10 metadata indexes per vectorize index.
*
* @default {}
* @see https://hub.nuxt.com/docs/features/vectorize
*
* @example
* ```ts
* vectorize: {
* products: {
* metric: 'cosine',
* dimensions: '768',
* metadataIndexes: { name: 'string', price: 'number', isActive: 'boolean' }
* },
* reviews: {
* metric: 'cosine',
* dimensions: '768',
* metadataIndexes: { rating: 'number' }
* }
* }
* ```
*/
vectorize?: {
[key: string]: {
metric: 'cosine' | 'euclidean' | 'dot-product';
dimensions: number;
metadataIndexes?: Record<string, 'string' | 'number' | 'boolean'>;
};
};
/**
* Set to `true`, 'preview', 'production' or <environment name> to use the remote storage.
* Only set the value on a project you are deploying outside of NuxtHub or Cloudflare.
* Or wrap it with $development to only use it in development mode.
* @default process.env.NUXT_HUB_REMOTE or --remote option when running `nuxt dev`
* @see https://hub.nuxt.com/docs/getting-started/remote-storage
*/
remote?: boolean | 'production' | 'preview' | string;
/**
* The URL of the NuxtHub Admin
* @default 'https://admin.hub.nuxt.com'
*/
url?: string;
/**
* The project's key on the NuxtHub platform, added with `npx nuxthub link`.
* @default process.env.NUXT_HUB_PROJECT_KEY
*/
projectKey?: string;
/**
* The user token to access the NuxtHub platform, added with `npx nuxthub login`
* @default process.env.NUXT_HUB_USER_TOKEN
*/
userToken?: string;
/**
* The URL of the deployed project, used to fetch the remote storage.
* @default process.env.NUXT_HUB_PROJECT_URL
*/
projectUrl?: string | (({ env, branch }: {
env: 'production' | 'preview' | string;
branch: string;
}) => string);
/**
* The secret key defined in the deployed project as env variable, used to fetch the remote storage from the projectUrl
* @default process.env.NUXT_HUB_PROJECT_SECRET_KEY
*/
projectSecretKey?: string;
/**
* The directory used for storage (D1, KV, R2, etc.) in development mode.
* @default '.data/hub'
*/
dir?: string;
/**
* The extra bindings for the project.
*
* Additional bindings are added in the following format:
* ```ts
* bindings: {
* compatibilityDate: '2025-01-15',
* compatibilityFlags: ['enable-feature'],
* hyperdrive: {
* POSTGRES: '<your-hyperdrive-id>'
* },
* <binding type>: {
* <BINDING NAME>: {
* // binding specific options
* },
* }
* }
* ```
*
* @example
* ```ts
* bindings: {
* compatibilityDate: '2025-01-15',
* compatibilityFlags: ['enable-feature'],
* hyperdrive: {
* POSTGRES: '<your-hyperdrive-id>'
* },
* analytics_engine: {
* DATASET: { dataset: 'my_dataset' },
* }
* }
* ```
*
* ### Prohibited binding types
* These features are already handled by NuxtHub.
* - `ai` → `hub.ai`
* - `assets` → `hub.workers`
* - `browser_rendering` → `hub.browser`
* - `vectorize` → `hub.vectorize`
*
* ### Workers vs Pages
* Only `compatibilityDate`, `compatibilityFlags` and `hyperdrive` are applied on Pages projects.
*
* @see https://hub.nuxt.com/changelog/observability-additional-bindings
*/
bindings?: {
/**
* The compatibility date for the project.
* @see https://developers.cloudflare.com/workers/configuration/compatibility-dates/
*/
compatibilityDate?: string;
/**
* Extra compatibility flags for the project.
* Note that NuxtHub will default to the Nitro compatibility flags for Cloudflare if not specified.
* @see https://developers.cloudflare.com/workers/configuration/compatibility-dates/#compatibility-flags
*/
compatibilityFlags?: string[];
/**
* The hyperdrive bindings for the project, used only when deployed on Cloudflare.
* @see https://hub.nuxt.com/docs/features/hyperdrive
* @default {}
* @example
* ```ts
* bindings: {
* hyperdrive: {
* POSTGRES: '<your-hyperdrive-id>'
* }
* }
* ```
*/
hyperdrive?: {
/**
* The key of the binding, accessible in the project as `process.env.<key>`.
* The value is the ID of the hyperdrive instance.
*/
[key: string]: string;
};
/**
* The observability settings for the project.
* @see https://developers.cloudflare.com/workers/observability/logs/workers-logs/#enable-workers-logs
*/
observability?: {
/**
* Enable and manage Worker Logs settings.
* @see https://developers.cloudflare.com/workers/observability/logs/workers-logs/
*/
logs?: boolean | {
/**
* @default true
* @see https://developers.cloudflare.com/workers/observability/logs/workers-logs/#invocation-logs
*/
invocation_logs?: boolean;
/**
* @see https://developers.cloudflare.com/workers/observability/logs/workers-logs/#head-based-sampling
*/
head_sampling_rate: number;
};
};
} & {
[K in Exclude<Extract<AdditionalCloudflareBindings, {
type: string;
}>['type'], ProhibitedBindingTypes>]?: Record<string, Omit<Extract<AdditionalCloudflareBindings, {
type: K;
}>, 'name' | 'type'>>;
} & {
[K in ProhibitedBindingTypes]?: never;
};
/**
* Cloudflare Access authentication for remote storage.
* @see https://hub.nuxt.com/recipes/cloudflare-access
*/
cloudflareAccess?: {
/**
* The client ID for Cloudflare Access.
* @default process.env.NUXT_HUB_CLOUDFLARE_ACCESS_CLIENT_ID
*/
clientId?: string;
/**
* The client secret for Cloudflare Access.
* @default process.env.NUXT_HUB_CLOUDFLARE_ACCESS_CLIENT_SECRET
*/
clientSecret?: string;
};
}
/**
* Additional bindings for Cloudflare Workers that aren't already integrated into NuxtHub.
* @see https://developers.cloudflare.com/api/resources/workers/subresources/scripts/methods/update/
*/
type ProhibitedBindingTypes = 'ai' | 'assets' | 'browser_rendering' | 'vectorize';
type AdditionalCloudflareBindings = WorkersBindingKindAnalyticsEngine | WorkersBindingKindDispatchNamespace | WorkersBindingKindJson | WorkersBindingKindMTLSCERT | WorkersBindingKindPlainText | WorkersBindingKindQueue | WorkersBindingKindService | WorkersBindingKindTailConsumer | WorkersBindingKindVersionMetadata;
interface WorkersBindingKindAnalyticsEngine {
dataset: string;
name: string;
type: 'analytics_engine';
}
interface WorkersBindingKindDispatchNamespace {
name: string;
namespace: string;
type: 'dispatch_namespace';
outbound?: {
params?: string[];
worker?: {
environment?: string;
service?: string;
};
};
}
interface WorkersBindingKindJson {
json: string;
name: string;
type: 'json';
}
interface WorkersBindingKindMTLSCERT {
certificate_id: string;
name: string;
type: 'mtls_certificate';
}
interface WorkersBindingKindPlainText {
name: string;
text: string;
type: 'plain_text';
}
interface WorkersBindingKindQueue {
name: string;
queue_name: string;
type: 'queue';
}
interface WorkersBindingKindService {
environment: string;
name: string;
service: string;
type: 'service';
}
interface WorkersBindingKindTailConsumer {
name: string;
service: string;
type: 'tail_consumer';
}
interface WorkersBindingKindVersionMetadata {
name: string;
type: 'version_metadata';
}
type PowOf2 = 1 | 2 | 4 | 8 | 16 | 32 | 64 | 128 | 256 | 512 | 1024;
type SizeUnit = 'B' | 'KB' | 'MB' | 'GB';
type BlobSize = `${PowOf2}${SizeUnit}`;
type BlobType = 'image' | 'video' | 'audio' | 'pdf' | 'text' | 'blob' | MimeType;
type FileSizeUnit = 'B' | 'KB' | 'MB' | 'GB';
interface BlobObject {
/**
* The pathname of the blob, used to @see {@link HubBlob.serve} the blob.
*/
pathname: string;
/**
* The content type of the blob.
*/
contentType: string | undefined;
/**
* The size of the blob in bytes.
*/
size: number;
/**
* The blob's etag, in quotes so as to be returned as a header.
*/
httpEtag: string;
/**
* The date the blob was uploaded at.
*/
uploadedAt: Date;
/**
* The HTTP metadata of the blob.
*/
httpMetadata: R2HTTPMetadata;
/**
* The custom metadata of the blob.
*/
customMetadata: Record<string, string>;
}
interface BlobUploadedPart {
/**
* The number of the part.
*/
partNumber: number;
/**
* The etag of the part.
*/
etag: string;
}
interface BlobMultipartUpload {
/**
* The pathname of the multipart upload.
*/
readonly pathname: string;
/**
* The upload id of the multipart upload.
*/
readonly uploadId: string;
/**
* Upload a single part to this multipart upload.
*/
uploadPart(partNumber: number, value: string | ReadableStream<any> | ArrayBuffer | ArrayBufferView | Blob): Promise<BlobUploadedPart>;
/**
* Abort the multipart upload.
*/
abort(): Promise<void>;
/**
* Completes the multipart upload.
*/
complete(uploadedParts: BlobUploadedPart[]): Promise<BlobObject>;
}
interface BlobListOptions {
/**
* The maximum number of blobs to return per request.
* @default 1000
*/
limit?: number;
/**
* The prefix to filter the blobs by.
*/
prefix?: string;
/**
* The cursor to list the blobs from (used for pagination).
*/
cursor?: string;
/**
* View prefixes as directory.
*/
folded?: boolean;
}
interface BlobPutOptions {
/**
* The content type of the blob.
*/
contentType?: string;
/**
* The content length of the blob.
*/
contentLength?: string;
/**
* If a random suffix is added to the blob pathname.
* @default false
*/
addRandomSuffix?: boolean;
/**
* The prefix to use for the blob pathname.
*/
prefix?: string;
/**
* The custom metadata of the blob.
*/
customMetadata?: Record<string, string>;
/**
* @deprecated Use customMetadata instead.
*/
[key: string]: any;
}
interface BlobMultipartOptions {
/**
* The content type of the blob.
*/
contentType?: string;
/**
* The content length of the blob.
*/
contentLength?: string;
/**
* If a random suffix is added to the blob pathname.
* @default false
*/
addRandomSuffix?: boolean;
/**
* The prefix to use for the blob pathname.
*/
prefix?: string;
/**
* The custom metadata of the blob.
*/
customMetadata?: Record<string, string>;
/**
* @deprecated Use customMetadata instead.
*/
[key: string]: any;
}
type HandleMPUResponse = {
action: 'create';
data: Pick<BlobMultipartUpload, 'pathname' | 'uploadId'>;
} | {
action: 'upload';
data: BlobUploadedPart;
} | {
action: 'complete';
data: BlobObject;
} | {
action: 'abort';
};
interface BlobUploadOptions {
/**
* The key to get the file/files from the request form.
* @default 'files'
*/
formKey?: string;
/**
* Whether to allow multiple files to be uploaded.
* @default true
*/
multiple?: boolean;
/**
* Options used for the ensure() method.
* @see https://hub.nuxt.com/docs/features/blob#ensureblob
*/
ensure?: BlobEnsureOptions;
/**
* Options used for the put() method.
* @see https://hub.nuxt.com/docs/features/blob#put
*/
put?: BlobPutOptions;
}
interface BlobEnsureOptions {
/**
* The maximum size of the blob (e.g. '1MB')
*/
maxSize?: BlobSize;
/**
* The allowed types of the blob (e.g. ['image/png', 'application/json', 'video'])
*/
types?: BlobType[];
}
interface BlobListResult {
/**
* The list of blobs.
*/
blobs: BlobObject[];
/**
* The Boolean indicating if there are more blobs to list.
*/
hasMore: boolean;
/**
* The cursor to use for pagination.
*/
cursor?: string;
/**
* The list of folders with `/` delimiter.
*/
folders?: string[];
}
interface BlobCredentialsOptions {
/**
* The permission of the credentials.
* @default 'admin-read-write'
*/
permission?: 'admin-read-write' | 'admin-read-only' | 'object-read-write' | 'object-read-only';
/**
* The ttl of the credentials in seconds.
* @default 900
*/
ttl?: number;
/**
* The prefixes to scope the credentials to.
*/
prefixes?: string[];
/**
* The pathnames to scope the credentials to.
*/
pathnames?: string[];
}
interface BlobCredentials {
/**
* The Cloudflare account id
*/
accountId: string;
/**
* The Cloudflare R2 bucket name
*/
bucketName: string;
/**
* The access key id for the R2 bucket
*/
accessKeyId: string;
/**
* The secret access key for the R2 bucket
*/
secretAccessKey: string;
/**
* The session token for the R2 bucket
*/
sessionToken: string;
}
type OmitDump<T> = Omit<T, 'dump'>;
type D1Database = OmitDump<D1Database$1>;
interface HubKV extends Storage {
/**
* Get all keys from the storage.
*
* @see https://hub.nuxt.com/docs/features/kv#list-all-keys
*/
keys: Storage['getKeys'];
/**
* Get an item from the storage.
*
* @param key The key to get
*
* @see https://hub.nuxt.com/docs/features/kv#get-an-item
*/
get: Storage['getItem'];
/**
* Set an item in the storage.
*
* @param key The key to set
* @param value The value to set
* @param options The options to set (optional)
* @param options.ttl The time to live in seconds (optional)
*
* @see https://hub.nuxt.com/docs/features/kv#set-an-item
*/
set: Storage['setItem'];
/**
* Check if an item exists in the storage.
*
* @param key The key to check
*
* @see https://hub.nuxt.com/docs/features/kv#has-an-item
*/
has: Storage['hasItem'];
/**
* Delete an item from the storage.
*
* @param key The key to delete
*
* @see https://hub.nuxt.com/docs/features/kv#delete-an-item
*/
del: Storage['removeItem'];
}
type Vectorize = Vectorize$1;
declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
export { _default as default };
export type { AdditionalCloudflareBindings, BlobCredentials, BlobCredentialsOptions, BlobEnsureOptions, BlobListOptions, BlobListResult, BlobMultipartOptions, BlobMultipartUpload, BlobObject, BlobPutOptions, BlobSize, BlobType, BlobUploadOptions, BlobUploadedPart, D1Database, FileSizeUnit, HandleMPUResponse, HubKV, ModuleHooks, ModuleOptions, PowOf2, SizeUnit, Vectorize, WorkersBindingKindAnalyticsEngine, WorkersBindingKindDispatchNamespace, WorkersBindingKindJson, WorkersBindingKindMTLSCERT, WorkersBindingKindPlainText, WorkersBindingKindQueue, WorkersBindingKindService, WorkersBindingKindTailConsumer, WorkersBindingKindVersionMetadata };