From eedc3839df29025924e13f971dee58add631a253 Mon Sep 17 00:00:00 2001 From: David Dal Busco Date: Thu, 19 Oct 2023 12:54:28 +0200 Subject: [PATCH] docs: nextjs guides (#56) --- docs/guides/nextjs.md | 172 ++++++++++++++++++++++++++++++++++++++++++ docs/guides/react.md | 7 +- 2 files changed, 176 insertions(+), 3 deletions(-) create mode 100644 docs/guides/nextjs.md diff --git a/docs/guides/nextjs.md b/docs/guides/nextjs.md new file mode 100644 index 00000000..48f8ff1d --- /dev/null +++ b/docs/guides/nextjs.md @@ -0,0 +1,172 @@ +--- +id: nextjs +title: Next.js +toc_min_heading_level: 2 +toc_max_heading_level: 2 +sidebar_position: 1 +--- + +# Use Juno with Next.js + +Learn how to create a Juno project developed with Next.js. + +## Table of contents + +- [Quickstart](#quickstart) +- [Note-taking app](#note-taking-app) +- [Hosting](#hosting) + +--- + +## Quickstart + +Learn how to create a [satellite], set up a collection, and save data from a React app. + +### 1. Set up a satellite and new collection + +[Create a new satellite](../add-juno-to-an-app/create-a-satellite.md) in the Juno's console. + +After your project is ready, create a collection in your datastore, which we'll call `demo` in the [console](https://console.juno.build). + +### 2. Create a Next.js app + +Use the [create-next-app](https://nextjs.org/docs/pages/api-reference/create-next-app) command, to create a Next.js app: + +```bash +npx create-next-app@latest my-juno-app +``` + +### 3. Install the Juno SDK core library + +Use `@junobuild/core` client library which provides a convenient interface for working with Juno from a Next.js app. + +Navigate to the Next.js app and install `@junobuild/core`. + +```bash +cd my-juno-app && npm i @junobuild/core +``` + +### 4. Insert data from your app + +In `Page.tsx`, assuming you're using TypeScript; otherwise, in the corresponding JavaScript file, initialize the library with your public satellite ID. + +Add an `insert` function to persist a document. + +```typescript +"use client"; + +import { useEffect, useState } from "react"; +import { type Doc, initJuno, setDoc } from "@junobuild/core"; + +type Record = { + hello: string; +}; + +export default function Home() { + const [record, setRecord] = useState | undefined>(undefined); + + // TODO: Replace the following satelliteId with your app's effective satellite ID. + useEffect(() => { + (async () => + await initJuno({ + satelliteId: "wjar4-kiaaa-aaaal-ab4va-cai", + }))(); + }, []); + + const insert = async () => { + const doc = await setDoc({ + collection: "demo", + doc: { + key: `my-key-${new Date().getTime()}`, + data: { + hello: "world", + }, + }, + }); + + setRecord(doc); + }; + + return ( + <> + + {record !== undefined && Key: {record.key}} + + ); +} +``` + +### 5. Start the app + +Start the app, go to [http://localhost:3000](http://localhost:3000) in a browser, click "Insert a document," and you should see the data successfully persisted in your satellite on the blockchain. + +--- + +## Note-taking app + +This example demonstrates how to build a basic note-taking app. The app authenticates and identifies the user, stores their notes in a simple key-pair database, some files in storage, and allows the user to log in and retrieve their data. The app uses: + +- Juno [datastore](../build/datastore.md): a simple key-pair database for storing user data and other information. +- Juno [storage](../build/storage.md): a file storage system to store and serve user-generated content, such as photos. +- Juno [authentication](../build/authentication.md): easy-to-use SDKs that support truly anonymous authentication. + +For sample code and instructions, visit the guide 👉 [GitHub repo](https://github.com/junobuild/examples/tree/main/next/diary). + +--- + +## Hosting + +If you're looking to deploy your existing app or website developed with Next.js and Juno, this guide is for you. + +### 1. Static exports + +The Internet Computer, including Juno, currently does not support Server Side Rendering. Therefore, it is recommended to generate a pre-rendered or client-side-only frontend application. + +We suggest using the [static exports](https://nextjs.org/docs/pages/building-your-application/deploying/static-exports) option from Next.js. + +In `next.config.js` file: + +```javascript +/** @type {import('next').NextConfig} */ +const nextConfig = { + output: "export", +}; + +module.exports = nextConfig; +``` + +### 2. Set up a satellite + +[Create a new satellite](../add-juno-to-an-app/create-a-satellite.md) in the Juno's console. + +### 3. Install Juno CLI and log in + +Install the Juno command line interface by executing the following command in your terminal: + +```bash +npm i -g @junobuild/cli +``` + +After the CLI is ready, log in to your satellite from your terminal to authenticate your device. + +```bash +juno login +``` + +### 4. Deploy + +Deploy your project by running the following command from your project’s root folder: + +```bash +juno deploy +``` + +### 5. Open + +Open your browser and you should see your deployed app or website. + +```bash +juno open +``` + +[satellite]: ../terminology.md#satellite diff --git a/docs/guides/react.md b/docs/guides/react.md index 6abc4ac0..8b865384 100644 --- a/docs/guides/react.md +++ b/docs/guides/react.md @@ -3,6 +3,7 @@ id: react title: React toc_min_heading_level: 2 toc_max_heading_level: 2 +sidebar_position: 2 --- # Use Juno with React @@ -32,7 +33,7 @@ After your project is ready, create a collection in your datastore, which we'll Create a React app using for example a [Vite](https://vitejs.dev/guide/) template. ```bash -npm create vite@latest my-app -- --template react +npm create vite@latest my-juno-app -- --template react ``` ### 3. Install the Juno SDK core library @@ -42,7 +43,7 @@ Use `@junobuild/core` client library which provides a convenient interface for w Navigate to the React app and install `@junobuild/core`. ```bash -cd my-app && npm i @junobuild/core +cd my-juno-app && npm i @junobuild/core ``` ### 4. Insert data from your app @@ -111,7 +112,7 @@ For detailed instructions, visit the guide 👉 [Build A Web3 App With React JS] ## Hosting -If you're looking to deploy your existing app or website developed with React without implementing any additional features with Juno, this guide is for you. +If you're looking to deploy your existing app or website developed with React and Juno, this guide is for you. ### 1. Set up a satellite