add instructions

Compiling instructions
2025-07-04 05:31:05 +00:00
parent bb83c6db33
commit 2a7a0fadce
1 changed files with 101 additions and 0 deletions
--- a/markdown_backend/steps.yml
+++ b/markdown_backend/steps.yml
@@ -0,0 +1,101 @@
+project_setup:
+      description: Setup Rust and Next.js to compile Rust to WASM for web use
+        prerequisites:
+            - Node.js >= 18
+                - Rust >= 1.70
+                    - wasm-pack installed (`cargo install wasm-pack`)
+                        - Next.js app created (`npx create-next-app@latest`)
+                            - Optional: TypeScript enabled
+                              steps:
+                                  - name: Create Rust crate
+                                        run: |
+                                                mkdir rust-wasm
+                                                        cd rust-wasm
+                                                                cargo new --lib wasm_core
+                                                                        cd wasm_core
+
+                                                                            - name: Add wasm dependencies to Cargo.toml
+                                                                                  file: rust-wasm/wasm_core/Cargo.toml
+                                                                                        append:
+                                                                                                dependencies:
+                                                                                                          wasm-bindgen: "0.2"
+                                                                                                                  [lib]:
+                                                                                                                            crate-type: ["cdylib"]
+                                                                                                                                    [package.metadata.wasm-pack.profile.release]
+                                                                                                                                              wasm-opt: true
+
+                                                                                                                                                  - name: Write simple Rust function
+                                                                                                                                                        file: rust-wasm/wasm_core/src/lib.rs
+                                                                                                                                                              content: |
+                                                                                                                                                                      use wasm_bindgen::prelude::*;
+
+                                                                                                                                                                              #[wasm_bindgen]
+                                                                                                                                                                                      pub fn greet(name: &str) -> String {
+                                                                                                                                                                                                  format!("Hello, {}!", name)
+                                                                                                                                                                                                          }
+
+                                                                                                                                                                                                              - name: Build WASM module with wasm-pack
+                                                                                                                                                                                                                    run: |
+                                                                                                                                                                                                                            cd rust-wasm/wasm_core
+                                                                                                                                                                                                                                    wasm-pack build --target web --out-dir ../pkg
+
+                                                                                                                                                                                                                                    nextjs_setup:
+                                                                                                                                                                                                                                      description: Integrate the WASM output into a Next.js app
+                                                                                                                                                                                                                                        steps:
+                                                                                                                                                                                                                                            - name: Move compiled WASM pkg to Next.js public or static
+                                                                                                                                                                                                                                                  run: |
+                                                                                                                                                                                                                                                          # Assuming your Next.js app is in ../my-app
+                                                                                                                                                                                                                                                                  mkdir -p ../my-app/public/wasm
+                                                                                                                                                                                                                                                                          cp -r ../rust-wasm/pkg/* ../my-app/public/wasm/
+
+                                                                                                                                                                                                                                                                              - name: Import and initialize WASM in React
+                                                                                                                                                                                                                                                                                    file: my-app/app/page.tsx
+                                                                                                                                                                                                                                                                                          content: |
+                                                                                                                                                                                                                                                                                                  'use client';
+                                                                                                                                                                                                                                                                                                          import { useEffect, useState } from "react";
+
+                                                                                                                                                                                                                                                                                                                  export default function Home() {
+                                                                                                                                                                                                                                                                                                                            const [output, setOutput] = useState("");
+
+                                                                                                                                                                                                                                                                                                                                      useEffect(() => {
+                                                                                                                                                                                                                                                                                                                                                  (async () => {
+                                                                                                                                                                                                                                                                                                                                                                const wasm = await import("../../public/wasm/wasm_core.js");
+                                                                                                                                                                                                                                                                                                                                                                              await wasm.default(); // init
+                                                                                                                                                                                                                                                                                                                                                                                            const result = wasm.greet("Next.js + Rust");
+                                                                                                                                                                                                                                                                                                                                                                                                          setOutput(result);
+                                                                                                                                                                                                                                                                                                                                                                                                                      })();
+                                                                                                                                                                                                                                                                                                                                                                                                                                }, []);
+
+                                                                                                                                                                                                                                                                                                                                                                                                                                          return <div className="p-4 font-mono text-xl">{output}</div>;
+                                                                                                                                                                                                                                                                                                                                                                                                                                                  }
+
+                                                                                                                                                                                                                                                                                                                                                                                                                                                      - name: Add TypeScript support (optional)
+                                                                                                                                                                                                                                                                                                                                                                                                                                                            tips:
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                    - Type declarations are not emitted automatically by wasm-pack
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                            - You can write your own `.d.ts` file for the exposed functions
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  example_file: my-app/types/wasm_core.d.ts
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        content: |
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                declare module "public/wasm/wasm_core.js" {
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          export function greet(name: string): string;
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    export default function init(): Promise<void>;
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            }
+
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                - name: Optimize WebAssembly (optional)
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tips:
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              - Install `binaryen` to use `wasm-opt`
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      - Run `wasm-pack build --release` with `wasm-opt` enabled
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              - Produces smaller, faster WASM binaries
+
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              dev_commands:
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                - command: cargo install wasm-pack
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    description: Install wasm-pack for building to WebAssembly
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      - command: wasm-pack build --target web
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          description: Build the Rust crate into WASM + JS bindings for browser
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            - command: npm run dev
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                description: Start your Next.js frontend
+
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                optional_advanced:
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  - name: Use `wasm-bindgen` directly (without wasm-pack)
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      reason: More control over output but more setup required
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        - name: Use `next-transpile-modules` to load WASM via import from `pkg/`
+                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            reason: Allows more direct integration but may need webpack tuning