feat: Add Trunk, Next.js, Nuxt Frontend Guides (#1405)

* feat: working on some mobile docs * docs: committing current state * working on it * Move to create section Signed-off-by: Lorenzo Lewis <[email protected]> * Switch to commandtabs component, update copy Signed-off-by: Lorenzo Lewis <[email protected]> * shift some files around Signed-off-by: Lorenzo Lewis <[email protected]> * move docs Signed-off-by: Lorenzo Lewis <[email protected]> * add to sidebar Signed-off-by: Lorenzo Lewis <[email protected]> * tweaks Signed-off-by: Lorenzo Lewis <[email protected]> * revert Signed-off-by: Lorenzo Lewis <[email protected]> * format Signed-off-by: Lorenzo Lewis <[email protected]> * phrasing updates Signed-off-by: Lorenzo Lewis <[email protected]> * Stub leptos guide Signed-off-by: Lorenzo Lewis <[email protected]> * Stub qwik Signed-off-by: Lorenzo Lewis <[email protected]> * stub Svelte Signed-off-by: Lorenzo Lewis <[email protected]> * Stub sycamore Signed-off-by: Lorenzo Lewis <[email protected]> * Stub vite Signed-off-by: Lorenzo Lewis <[email protected]> * stub webpack Signed-off-by: Lorenzo Lewis <[email protected]> * stub Yew Signed-off-by: Lorenzo Lewis <[email protected]> * fix typo Signed-off-by: Lorenzo Lewis <[email protected]> * Update description Signed-off-by: Lorenzo Lewis <[email protected]> * update descriptions and comments Signed-off-by: Lorenzo Lewis <[email protected]> * Add version to trunk guide Signed-off-by: Lorenzo Lewis <[email protected]> * Revise wording Signed-off-by: Lorenzo Lewis <[email protected]> * update to mention upstream issues, phrasing Signed-off-by: Lorenzo Lewis <[email protected]> * Add telemetry as optional to checklist Signed-off-by: Lorenzo Lewis <[email protected]> * Remove optional build object in config Signed-off-by: Lorenzo Lewis <[email protected]> * Apply suggestions from code review * remove setting that's already default Signed-off-by: Lorenzo Lewis <[email protected]> * rename Svelte file Signed-off-by: Lorenzo Lewis <[email protected]> * Update src/content/docs/2/guide/frontend/trunk.mdx Co-authored-by: Simon Hyll <[email protected]> * Cleanup Trunk Signed-off-by: Lorenzo Lewis <[email protected]> * setup > configuration, remove install Signed-off-by: Lorenzo Lewis <[email protected]> * Add steps Signed-off-by: Lorenzo Lewis <[email protected]> * Add steps Signed-off-by: Lorenzo Lewis <[email protected]> * Update src/content/docs/2/guide/frontend/nuxt.mdx * Add link to environment variables Signed-off-by: Lorenzo Lewis <[email protected]> * update to default port Signed-off-by: Lorenzo Lewis <[email protected]> * Enable for i18n * add environment-variables stub Signed-off-by: Lorenzo Lewis <[email protected]> * Update src/content/docs/2/guide/frontend/trunk.mdx Co-authored-by: Simon Hyll <[email protected]> --------- Signed-off-by: Lorenzo Lewis <[email protected]> Co-authored-by: Lorenzo Lewis <[email protected]>
tauri-apps · Sep 2, 2023 · 1b4b351 · 1b4b351
1 parent 4e1f43a
commit 1b4b351
Show file tree

Hide file tree

Showing 14 changed files with 382 additions and 42 deletions.
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -87,6 +87,10 @@ export default defineConfig({
 							label: 'Create a Project',
 							link: '/2/guide/create/',
 						},
+						{
+							label: 'Frontend Configuration',
+							link: '/2/guide/frontend/',
+						},
 						{
 							label: 'Upgrade & Migrate',
 							link: '2/guide/upgrade-migrate',

diff --git a/src/content/docs/2/guide/create/index.mdx b/src/content/docs/2/guide/create/index.mdx
@@ -62,12 +62,11 @@ Follow along with the prompts to choose your project name, frontend language, pa
 
 :::tip[Not sure what to choose?]
 
-We use [SolidJS](https://www.solidjs.com) throughout the Tauri documentation and examples. For the easiest way to follow along we recommend the following:
+We recommend starting with the vanilla template (HTML, CSS, and JavaScript without a frontend framework) to get started. You can always [integrate a frontend framework](/2/guide/create/existing-project) later.
 
 - Choose which language to use for your frontend: `TypeScript / JavaScript`
 - Choose your package manager: `pnpm`
-  {/* TODO: Change phrasing in CTA from UI to frontend and Solid to SolidJS */}
-- Choose your UI template: `Solid`
+- Choose your UI template: `Vanilla`
 - Choose your UI flavor: `TypeScript`
 
 :::
@@ -76,58 +75,33 @@ We use [SolidJS](https://www.solidjs.com) throughout the Tauri documentation and
 
 After `create-tauri-app` has complete you can navigate into your project's folder, install dependencies, then use the [Tauri CLI](/2/reference/cli) to start the development server:
 
-<Tabs>
-  <TabItem label="npm">
+import CommandTabs from '@components/CommandTabs.astro';
 
-    ```sh
-    cd my-tauri-app
+<CommandTabs
+	npm="cd my-tauri-app
     npm install
-    npm run tauri dev
-    ```
-
-  </TabItem>
-  <TabItem label="Yarn">
-
-    ```sh
-    cd my-tauri-app
+    npm run tauri dev"
+	yarn="cd my-tauri-app
     yarn install
-    yarn tauri dev
-    ```
-
-  </TabItem>
-  <TabItem label="pnpm">
-
-    ```sh
-    cd my-tauri-app
+    yarn tauri dev"
+	pnpm="cd my-tauri-app
     pnpm install
-    pnpm tauri dev
-    ```
-
-  </TabItem>
-  <TabItem label="Cargo">
+    pnpm tauri dev"
+	cargo="cd my-tauri-app
+    cargo tauri dev"
+/>
 
-    ```sh
-    cd my-tauri-app
-    cargo tauri dev
-    ```
-
-  </TabItem>
-</Tabs>
-
-You'll now see a new window open with your app running:
-
-TODO: Image of app here
+You'll now see a new window open with your app running.
 
 **Congratulations!** You've made your Tauri app! 🚀
 
-<Card title="Next Steps" icon="rocket">
+## Next Steps
 
+- [Add and Configure a Frontend Framework](/2/guide/frontend)
 - [Tauri Command Line Interface (CLI) Reference](/2/reference/cli)
 - [Learn how to build your Tauri app](/2/guide/build)
 - [Discover additional features and recipes to extend Tauri](/2/guide/list)
 
-</Card>
-
 <Card title="Additional Resources" icon="document">
 
 List to best practices, blog posts, etc.

diff --git a/src/content/docs/2/guide/frontend/index.mdx b/src/content/docs/2/guide/frontend/index.mdx
@@ -0,0 +1,50 @@
+---
+title: Frontend Configuration
+i18nReady: true
+---
+
+import { LinkCard, CardGrid } from '@astrojs/starlight/components';
+
+Tauri is frontend agnostic and supports most frontend frameworks out of the box. However, sometimes a framework need a bit of extra configuration to integrate with Tauri. Below is a list of frameworks with recommended configurations.
+
+If a framework is not listed then it may work with Tauri with no additional configuration needed or it could have not been documented yet. Any contributions to add a framework that may require additional configuration are welcome to help others in the Tauri community.
+
+:::tip[Framework Not Listed?]
+
+Don't see a framework listed? It may work with Tauri without any additional configuration required. Read the [configuration checklist](#configuration-checklist) for any common configurations to check for.
+
+:::
+
+## JavaScript
+
+<CardGrid>
+	<LinkCard title="Next.js" href="/2/guide/frontend/nextjs" />
+	<LinkCard title="Nuxt" href="/2/guide/frontend/nuxt" />
+	<LinkCard title="Qwik" href="/2/guide/frontend/qwik" />
+	<LinkCard title="SvelteKit" href="/2/guide/frontend/sveltekit" />
+	<LinkCard title="Vite" href="/2/guide/frontend/vite" />
+	<LinkCard title="Webpack" href="/2/guide/frontend/webpack" />
+</CardGrid>
+
+## Rust
+
+<CardGrid>
+	<LinkCard title="Leptos" href="/2/guide/frontend/leptos" />
+	<LinkCard title="Sycamore" href="/2/guide/frontend/sycamore" />
+	<LinkCard title="Trunk" href="/2/guide/frontend/trunk" />
+	<LinkCard title="Yew" href="/2/guide/frontend/yew" />
+</CardGrid>
+
+## Configuration Checklist
+
+Conceptually Tauri acts as a static web host. You need to provide Tauri with a folder containing some mix of HTML, CSS, Javascript and possibly WASM that can be served to the webview Tauri provides.
+
+Below is a checklist of common scenarios needed to integrate a frontend with Tauri:
+
+{/* TODO: Link to core concept of SSG/SSR, etc. */}
+{/* TODO: Link to mobile development server guide */}
+{/* TODO: Concept of how to do a client-server relationship? */}
+
+- Use static site generation (SSG). Tauri doesn't officially support server based alternatives (such as SSR).
+- For mobile development, a development server of some kind is necessary that can host the frontend on your internal IP.
+- Use a proper client-server relationship between your app and your API's (no hybrid solutions with SSR).
diff --git a/src/content/docs/2/guide/frontend/leptos.mdx b/src/content/docs/2/guide/frontend/leptos.mdx
@@ -0,0 +1,7 @@
+---
+title: Leptos
+---
+
+import Stub from '@components/Stub.astro';
+
+<Stub />
diff --git a/src/content/docs/2/guide/frontend/nextjs.mdx b/src/content/docs/2/guide/frontend/nextjs.mdx
@@ -0,0 +1,103 @@
+---
+title: Next.js
+i18nReady: true
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import CommandTabs from '@components/CommandTabs.astro';
+
+Next.js is a React framework. Learn more about Next.js at https://nextjs.org. This guide is accurate as of Next.js 13.4.19.
+
+## Checklist
+
+- Use static exports by setting `output: 'export'`. Tauri doesn't support server-based solutions.
+- Use `internal-ip` for mobile compatibility so you can configure `assetPrefix`. This is required so that the server properly resolves assets.
+- Use `out/` as `distDir` in `tauri.conf.json`.
+
+## Example Configuration
+
+1. Install `internal-ip` for mobile development:
+
+<CommandTabs
+	npm="npm install --save-dev internal-ip"
+	yarn="yarn add -D internal-ip"
+	pnpm="pnpm add -D internal-ip"
+/>
+
+2. Update Tauri configuration:
+
+<Tabs>
+	<TabItem label="npm">
+
+```json
+// tauri.conf.json
+{
+	"build": {
+		"beforeDevCommand": "npm run dev",
+		"beforeBuildCommand": "npm run build",
+		"devPath": "http://localhost:3000",
+		"distDir": "../dist"
+	}
+}
+```
+
+</TabItem>
+<TabItem label="yarn">
+
+```json
+// tauri.conf.json
+{
+	"build": {
+		"beforeDevCommand": "yarn dev",
+		"beforeBuildCommand": "yarn generate",
+		"devPath": "http://localhost:3000",
+		"distDir": "../dist"
+	}
+}
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```json
+// tauri.conf.json
+{
+	"build": {
+		"beforeDevCommand": "pnpm dev",
+		"beforeBuildCommand": "pnpm generate",
+		"devPath": "http://localhost:3000",
+		"distDir": "../dist"
+	}
+}
+```
+
+</TabItem>
+</Tabs>
+
+3. Update Next.js configuration:
+
+```ts
+// next.conf.ts
+const isProd = process.env.NODE_ENV === 'production';
+module.exports = async (phase, { defaultConfig }) => {
+	let internalHost = null;
+	// In dev mode we use the internal-ip to serve the assets
+	if (!isProd) {
+		const { internalIpV4 } = await import('internal-ip');
+		internalHost = await internalIpV4();
+	}
+	const nextConfig = {
+		// Ensure Next.js uses SSG instead of SSR
+		// https://nextjs.org/docs/pages/building-your-application/deploying/static-exports
+		output: 'export',
+		// Note: This experimental feature is required to use NextJS Image in SSG mode.
+		// See https://nextjs.org/docs/messages/export-image-api for different workarounds.
+		images: {
+			unoptimized: true,
+		},
+		// Configure assetPrefix or else the server won't properly resolve your assets.
+		assetPrefix: isProd ? null : `http://${internalHost}:3000`,
+	};
+	return nextConfig;
+};
+```
diff --git a/src/content/docs/2/guide/frontend/nuxt.mdx b/src/content/docs/2/guide/frontend/nuxt.mdx
@@ -0,0 +1,101 @@
+---
+title: Nuxt
+i18nReady: true
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Learn more about Nuxt at https://nuxt.com. This guide is accurate as of Nuxt 3.7.
+
+## Checklist
+
+- Use SSG by setting `ssr: false`. Tauri doesn't support server based solutions.
+- Set host to `0.0.0.0`.
+- Use `dist/` as `distDir` in `tauri.conf.json`.
+- Compile using `nuxi generate`.
+- (Optional): Disable telemetry by setting `telemetry: false` in `nuxt.config.ts`.
+
+## Example Configuration
+
+1. Update Tauri configuration:
+
+<Tabs>
+	<TabItem label="npm">
+
+```json
+// tauri.conf.json
+{
+	"build": {
+		"beforeDevCommand": "npm run dev",
+		"beforeBuildCommand": "npm run generate",
+		"devPath": "http://localhost:3000",
+		"distDir": "../dist"
+	}
+}
+```
+
+	</TabItem>
+	<TabItem label="yarn">
+
+```json
+// tauri.conf.json
+{
+	"build": {
+		"beforeDevCommand": "yarn dev",
+		"beforeBuildCommand": "yarn generate",
+		"devPath": "http://localhost:3000",
+		"distDir": "../dist"
+	}
+}
+```
+
+	</TabItem>
+	<TabItem label="pnpm">
+
+```json
+// tauri.conf.json
+{
+	"build": {
+		"beforeDevCommand": "pnpm dev",
+		"beforeBuildCommand": "pnpm generate",
+		"devPath": "http://localhost:3000",
+		"distDir": "../dist"
+	}
+}
+```
+
+	</TabItem>
+</Tabs>
+
+2. Update Nuxt configuration:
+
+```ts
+export default defineNuxtConfig({
+	// (optional) Enable the Nuxt devtools
+	devtools: { enabled: true },
+	// Enable SSG
+	ssr: false,
+	vite: {
+		// Better support for Tauri CLI output
+		clearScreen: false,
+		// Enable environment variables
+		// Additional environment variables can be found at
+		// https://tauri.app/2/reference/environment-variables/
+		envPrefix: ['VITE_', 'TAURI_'],
+		server: {
+			// Tauri requires a consistent port
+			strictPort: true,
+			// Enables the development server to be discoverable by other devices for mobile development
+			host: '0.0.0.0',
+			hmr: {
+				// Use websocket for mobile hot reloading
+				protocol: 'ws',
+				// Make sure it's available on the network
+				host: '0.0.0.0',
+				// Use a specific port for hmr
+				port: 5183,
+			},
+		},
+	},
+});
+```
diff --git a/src/content/docs/2/guide/frontend/qwik.mdx b/src/content/docs/2/guide/frontend/qwik.mdx
@@ -0,0 +1,7 @@
+---
+title: Qwik
+---
+
+import Stub from '@components/Stub.astro';
+
+<Stub />
diff --git a/src/content/docs/2/guide/frontend/svelte.mdx b/src/content/docs/2/guide/frontend/svelte.mdx
@@ -0,0 +1,7 @@
+---
+title: Svelte
+---
+
+import Stub from '@components/Stub.astro';
+
+<Stub />
diff --git a/src/content/docs/2/guide/frontend/sycamore.mdx b/src/content/docs/2/guide/frontend/sycamore.mdx
@@ -0,0 +1,7 @@
+---
+title: Sycamore
+---
+
+import Stub from '@components/Stub.astro';
+
+<Stub />