Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update the storage page #2086

Merged
merged 4 commits into from
Jan 23, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 28 additions & 47 deletions docs/content/1.guide/4.storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,33 @@ Nitro provides a built-in storage layer that can abstract filesystem or database

`useStorage()` is an instance of [createStorage](https://unstorage.unjs.io/getting-started/usage) using the [memory driver](https://unstorage.unjs.io/drivers/memory).

**Example:** Simple (in memory) operations
By default, Nitro will also mount the current directory using the filesystem driver, using a prefix and where each folder serve to extend the prefix.

```js
- Every file will be under the `root` base.
- Every source file will be under the `src` base. (By default, `src` is the `root` base)

## Usage

To use the storage layer, you can use the `useStorage()` and call `getItem` to retrieve an item and `setItem` to set an item.

```ts
await useStorage().setItem('test:foo', { hello: 'world' })
await useStorage().getItem('test:foo')

// You can also specify the base in useStorage(base)
await useStorage('test').setItem('foo', { hello: 'world' })
await useStorage('test').getItem('foo')
// `useStorage` and chained functions support a generic type to infer the return type
await useStorage<{ hello: string }>('test').getItem('foo')
await useStorage('test').getItem<{ hello: string }>('foo')
```

See [Unstorage](https://unstorage.unjs.io/getting-started/usage) for detailed usage.

## Mountpoints
## Mount Points

You can mount storage drivers using the `storage` option:
You can mount storage drivers using the `storage` option in the [Nitro config](/guide/config) file.

The key is the mount point name, and the value is the driver name and configuration. You can find the driver list on [unstorage documentation](https://unstorage.unjs.io/) with their configuration. You can mount multiple drivers.

::code-group
```ts [nitro.config.ts]
Expand Down Expand Up @@ -58,14 +69,13 @@ export default defineNuxtConfig({
```
::

::alert{type="warning"}
`cache` is a reserved mount point for the [cache layer](/guide/cache). Do not use it unless you want to overwrite the cache layer.
::

### Runtime configuration

In scenarios where the mount point configuration is not known until runtime, Nitro can dynamically add mount points during startup using [plugins](/guide/plugins):

::alert{type="info"}
This is a temporary workaround, with a better solution coming in the future! Keep a lookout on the GitHub issue [here](https://github.com/unjs/nitro/issues/1161#issuecomment-1511444675).
::
In scenarios where the mount point configuration is not known until runtime, Nitro can dynamically add mount points during startup using [plugins](/guide/plugins).

::code-group
```ts [plugins/storage.ts]
Expand Down Expand Up @@ -110,46 +120,15 @@ export default defineNuxtConfig({
```
::

::alert{type="warning"}
This is a temporary workaround, with a better solution coming in the future! Keep a lookout on the GitHub issue [here](https://github.com/unjs/nitro/issues/1161#issuecomment-1511444675).
::

Usage:

```js
await useStorage('redis').setItem('foo', { hello: 'world' })
pi0 marked this conversation as resolved.
Show resolved Hide resolved
await useStorage('redis').getItem('foo')
// or
await useStorage().setItem('redis:foo', { hello: 'world' })
await useStorage().getItem('redis:foo')
```

Usage with [generics](https://unstorage.unjs.io/getting-started/usage#generic-types):

```ts
await useStorage().getItem<string>('foo')
// => string
await useStorage<string>().getItem('foo')
// => string

await useStorage<string>().setItem('foo', 123) // ts error

type Foo = { data: number }

await useStorage().getItem<Foo>('foo')
// => Foo
```

You can find the list of drivers on [unstorage documentation](https://unstorage.unjs.io/).

In development, Nitro adds the `cache` mountpoint using the [FS driver](https://unstorage.unjs.io/drivers/fs) writting to `.nitro/cache` or `.nuxt/cache` if using [Nuxt](https://nuxt.com).

```js
await useStorage('cache').setItem('foo', { hello: 'world' })
await useStorage('cache').getItem('foo')
```

## Development only Storage

## Development storage
You can use the `devStorage` key to overwrite the storage configuration during development. This is very useful when you use a database in production and want to use the filesystem in development.

You can use the `devStorage` key to overwrite the storage configuration during development, very useful when you use a database in production and want to use the filesystem in development.
In order to use the `devStorage` key, you need to use the `nitro dev` command and the key in the `storage` option must be the same as the production one.

::code-group
```ts [nitro.config.ts]
Expand Down Expand Up @@ -191,3 +170,5 @@ export default defineNuxtConfig({
})
```
::

You will also be able to access to a `build` namespace in the storage layer only during development. It contains file generated by Nitro.