docs: datastore vs storage

docs/build/authentication/index.md

@@ -16,7 +16,7 @@ Juno allows you to securely identify users **anonymously** and save their data o
 
 Our easy-to-use SDKs support authentication through [Internet Identity] and [NFID].
 
-Juno Authentication integrates tightly with other Juno services like [datastore](../datastore/index.md) and [storage](../storage/index.md).
+Juno Authentication integrates tightly with other Juno services like [datastore](../datastore/index.mdx) and [storage](../storage/index.mdx).
 
 You can manage your users in the [authentication](https://console.juno.build/authentication) view in Juno's console. A new entry is created when a user successfully signs in.
 

docs/build/components/datastore-storage.md

@@ -0,0 +1,27 @@
+Juno gives you two ways to persist data. Both follow a collections-based architecture, but they serve different purposes and behave differently in practice.
+
+| Feature                | **Datastore** (Structured)       | **Storage** (Files)                           |
+| ---------------------- | -------------------------------- | --------------------------------------------- |
+| Use case               | App state, user profiles, config | Images, files, generated user content         |
+| Data format            | JSON-like documents              | Binary files                                  |
+| Identifier             | `key` (string you define)        | `fullPath` (auto or custom)                   |
+| Accessible via web URL | No                               | Yes                                           |
+| Size limit             | Max 2 MB per document            | Chunked; limited by available Satellite space |
+
+**`key` vs `fullPath`**
+
+Both Datastore and Storage use a unique identifier per item — but they refer to different things and are used differently.
+
+- **Datastore → `key`**:
+
+  - A unique string you assign to each document within a collection.
+  - Used to retrieve, update, or delete a specific document.
+  - Commonly a UUID (e.g. `crypto.randomUUID()`), a nanoid, or any meaningful string like a slug or user ID.
+  - Example: `bafkb4by...`, `user:42`, or `config/theme`.
+
+- **Storage → `fullPath`**:
+  - The full path of an asset used to build a valid web URL.
+  - It's automatically generated from the uploaded filename unless explicitly set.
+  - The `fullPath` must include the collection name (except for your app's frontend assets like HTML, JS, etc.).
+  - Used to serve, list, or delete files.
+  - Example: `/images/logo.png` (collection: `images`) or `/avatars/user42/profile.jpg` (collection: `avatars`).

docs/build/datastore/index.md → docs/build/datastore/index.mdx

@@ -12,7 +12,7 @@ Use it for structured data like user profiles, tasks, settings, or other data of
 
 :::tip
 
-For binary files like images or files, use the [Storage](../storage/index.md) instead.
+For binary files like images or files, use the [Storage](../storage/index.mdx) instead.
 
 :::
 
@@ -40,7 +40,7 @@ In essence, a "Datastore" functions as a keypair store.
 
 Each satellite has specific memory limits. For detailed information, please refer to the related [documentation](../../miscellaneous/memory.md) page.
 
-As for documents, they can be up to 2MB in size. However, larger files can be saved in the [storage](build/storage/index.md).
+As for documents, they can be up to 2MB in size. However, larger files can be saved in the [storage](build/storage/index.mdx).
 
 ---
 
@@ -49,3 +49,11 @@ As for documents, they can be up to 2MB in size. However, larger files can be sa
 The Datastore supports various configuration options to fine-tune its behavior, such as resource limits and operational constraints. For a detailed explanation of all available options, see the [configuration](../../reference/configuration.mdx#datastore) section.
 
 [satellite]: ../../terminology.md#satellite
+
+---
+
+## Datastore vs Storage
+
+import DatastoreVsStorage from "../components/datastore-storage.md";
+
+<DatastoreVsStorage />

docs/build/storage/development.mdx

@@ -372,7 +372,7 @@ There are multiple ways to delete assets from your Storage.
 
 ### Delete asset
 
-To delete an asset, you only need to provide its `fullPath`. Unlike the [datastore](../datastore/index.md), there is no timestamp validation performed when deleting an asset.
+To delete an asset, you only need to provide its `fullPath`. Unlike the [datastore](../datastore/index.mdx), there is no timestamp validation performed when deleting an asset.
 
 ```typescript
 import { deleteAsset } from "@junobuild/core";

docs/build/storage/index.md → docs/build/storage/index.mdx

@@ -11,7 +11,7 @@ It provides a simple way to upload, serve, and delete files, with support for mu
 
 :::tip
 
-For structured data, use the [Datastore](../datastore/index.md) instead.
+For structured data, use the [Datastore](../datastore/index.mdx) instead.
 
 :::
 
@@ -53,4 +53,12 @@ If you're configuring the hosting behavior of your site, start by checking out t
 
 For a complete list of available Storage options, refer to the [configuration](../../reference/configuration.mdx) section.
 
+---
+
+## Datastore vs Storage
+
+import DatastoreVsStorage from "../components/datastore-storage.md";
+
+<DatastoreVsStorage />
+
 [satellite]: ../../terminology.md#satellite

docs/faq.md

@@ -32,7 +32,7 @@ In the unlikely event of Juno's disappearance, you, as the sole controller of yo
 
 ### Can I just deploy my website on the Internet Computer?
 
-Absolutely! With Juno, you have the flexibility to choose the level of functionality you want for your project. Whether you simply want to host your static website on the [Internet Computer] or take advantage of Juno's rich features like [authentication](build/authentication/index.md), [datastore](./build/datastore/index.md), and [storage](./build/storage/index.md) for building dynamic dapps, the choice is yours.
+Absolutely! With Juno, you have the flexibility to choose the level of functionality you want for your project. Whether you simply want to host your static website on the [Internet Computer] or take advantage of Juno's rich features like [authentication](build/authentication/index.md), [datastore](build/datastore/index.mdx), and [storage](build/storage/index.mdx) for building dynamic dapps, the choice is yours.
 
 ### Is Juno a project of the DFINITY foundation?
 

docs/guides/angular.mdx

@@ -153,8 +153,8 @@ import WhatsNext from "./components/whats-next.md";
 This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features:
 
 - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication.
-- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information.
-- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos.
+- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information.
+- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos.
 
 Using the Juno CLI, you can easily scaffold this app.
 

docs/guides/nextjs.mdx

@@ -157,8 +157,8 @@ import WhatsNext from "./components/whats-next.md";
 This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features:
 
 - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication.
-- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information.
-- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos.
+- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information.
+- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos.
 
 Using the Juno CLI, you can easily scaffold this app.
 

docs/guides/react.mdx

@@ -150,8 +150,8 @@ import WhatsNext from "./components/whats-next.md";
 This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features:
 
 - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication.
-- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information.
-- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos.
+- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information.
+- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos.
 
 Using the Juno CLI, you can easily scaffold this app.
 

docs/guides/sveltekit.mdx

@@ -150,8 +150,8 @@ import WhatsNext from "./components/whats-next.md";
 This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features:
 
 - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication.
-- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information.
-- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos.
+- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information.
+- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos.
 
 Using the Juno CLI, you can easily scaffold this app.
 

docs/guides/vue.mdx

@@ -142,8 +142,8 @@ import WhatsNext from "./components/whats-next.md";
 This example demonstrates how to quickly deploy a basic note-taking app that integrates Juno's core features:
 
 - [Authentication](../build/authentication/index.md): easy-to-use SDKs that support truly anonymous authentication.
-- [Datastore](../build/datastore/index.md): a simple key-pair database for storing user data and other information.
-- [Storage](../build/storage/index.md): a file storage system to store and serve user-generated content, such as photos.
+- [Datastore](../build/datastore/index.mdx): a simple key-pair database for storing user data and other information.
+- [Storage](../build/storage/index.mdx): a file storage system to store and serve user-generated content, such as photos.
 
 Using the Juno CLI, you can easily scaffold this app.
 

docs/intro.mdx

@@ -47,8 +47,8 @@ And during development, the environment mirrors production as closely as possibl
 Learn more about the available products, from auth and data to hosting and functions.
 
 - [Authentication](build/authentication/index.md)
-- [Datastore](build/datastore/index.md)
-- [Storage](build/storage/index.md)
+- [Datastore](build/datastore/index.mdx)
+- [Storage](build/storage/index.mdx)
 - [Hosting](build/hosting/index.md)
 - [Functions](build/functions/index.md)
 - [Analytics](build/analytics/index.md)

docs/miscellaneous/access-keys.md

@@ -31,7 +31,7 @@ Each access key is assigned a **role** that defines what it can do:
 | **Write**       | Editor        | ✅         | ✅               | ✅                     | ❌                      |
 | **Submit**      | Submitter     | ✅         | ❌               | ❌                     | ❌                      |
 
-An **administrator** can perform tasks such as configuring or deploying an app, topping up a mission control or satellite, creating a new collection in the [datastore](../build/datastore/index.md) or [storage](../build/storage/index.md), or configuring a custom domain in the [hosting](../build/hosting/index.md).
+An **administrator** can perform tasks such as configuring or deploying an app, topping up a mission control or satellite, creating a new collection in the [datastore](../build/datastore/index.mdx) or [storage](../build/storage/index.mdx), or configuring a custom domain in the [hosting](../build/hosting/index.md).
 
 An **editor** can publish new serverless function versions to a Satellite’s CDN, deploy your frontend application, and read data from a collection. However, it cannot directly upgrade a Satellite or start/stop a module.
 

docs/miscellaneous/memory.md

@@ -6,7 +6,7 @@ This page explains how memory works conceptually and how you can monitor its usa
 
 ## General Memory Usage
 
-Every module — whether it's a [satellite], [orbiter], or your [mission control] — consumes memory in multiple ways. Some of that memory is directly controlled by your code, like the data you store in your [datastore](../build/datastore/index.md) or [storage](../build/storage/index.md). Other parts are more structural: global variables, the WASM binary (the container code itself), snapshots, and even system metadata contribute to your overall memory footprint.
+Every module — whether it's a [satellite], [orbiter], or your [mission control] — consumes memory in multiple ways. Some of that memory is directly controlled by your code, like the data you store in your [datastore](../build/datastore/index.mdx) or [storage](../build/storage/index.mdx). Other parts are more structural: global variables, the WASM binary (the container code itself), snapshots, and even system metadata contribute to your overall memory footprint.
 
 To help you understand and optimize memory usage, the Console displays a detailed breakdown under each module's overview tab. These metrics are especially helpful for staying within limits, controlling costs, and avoiding issues during upgrades.
 
@@ -53,7 +53,7 @@ In contrast, `heap` memory is best reserved for:
 - Serving your frontend assets (HTML, JS, images, etc.).
 - Small, ephemeral datasets that benefit from fast access and won't push the 1 GB heap limit.
 
-This is why both the [datastore](../build/datastore/index.md) and [storage](../build/storage/index.md) support both memory types — but default to `stable`, which is also the **recommended** option.
+This is why both the [datastore](../build/datastore/index.mdx) and [storage](../build/storage/index.mdx) support both memory types — but default to `stable`, which is also the **recommended** option.
 
 ### Default usage
 

docs/terminology.md

@@ -37,7 +37,7 @@ Learn more about [computation and storage costs](https://internetcomputer.org/do
 
 ## Doc
 
-"doc" is a commonly used shorthand in Juno for a "document of the Datastore". Wherever you see the term "doc" in the codebase or documentation, it refers specifically to a document entity managed by the [Datastore](./build/datastore/index.md). This abbreviation is used for brevity and consistency throughout the project.
+"doc" is a commonly used shorthand in Juno for a "document of the Datastore". Wherever you see the term "doc" in the codebase or documentation, it refers specifically to a document entity managed by the [Datastore](build/datastore/index.mdx). This abbreviation is used for brevity and consistency throughout the project.
 
 ## ICP