{"owner":"leptos-rs","repo":"leptos","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":2293,"categories":["project-spec"],"hasMcp":false,"mcpConfig":null,"found":["ARCHITECTURE.md"],"skills":{"ARCHITECTURE.md":"# Architecture\n\nThe goal of this document is to make it easier for contributors (and anyone\nwho’s interested!) to understand the architecture of the framework.\n\nThe whole Leptos framework is built from a series of layers. Each of these layers\ndepends on the one below it, but each can be used independently from the ones\nbuilt on top of it. While running a command like `cargo leptos new --git \nleptos-rs/start` pulls in the whole framework, it’s important to remember that\nnone of this is magic: each layer of that onion can be stripped away and\nreimplemented, configured, or adapted as needed, incrementally.\n\n> Everything that follows will assume you have a good working understanding\n> of the framework. There will be explanations of how some parts of it work\n> or fit together, but these are not docs. They assume you know what I’m\n> talking about.\n\n## The Reactive System: `leptos_reactive`\n\nThe reactive system allows you to define dynamic values (signals),\nthe relationships between them (derived signals and memos), and the side effects\nthat run in response to them (effects).\n\nThese concepts are completely independent of the DOM and can be used to drive\nany kind of reactive updates. The reactive system is based on the assumption\nthat data is relatively cheap, and side effects are relatively expensive. Its\ngoal is to minimize those side effects (like updating the DOM or making a network\nrequests) as infrequently as possible.\n\nThe reactive system is implemented as a single data structure that exists at\nruntime. In exchange for giving ownership over a value to the reactive system\n(by creating a signal), you receive a `Copy + 'static` identifier for its\nlocation in the reactive system. This enables most of the ergonomics of storing\nand sharing state, the use of callback closures without lifetime issues, etc.\nThis is implemented by storing signals in a slotmap arena. The signal, memo,\nand scope types that are exposed to users simply carry around an index into that\nslotmap.\n\n> Items owned by the reactive system are dropped when the corresponding reactive\n> scope is dropped, i.e., when the component or section of the UI they’re\n> created in is removed. In a sense, Leptos implements a “garbage collector”\n> in which the lifetime of data is tied to the lifetime of the UI, not Rust’s\n> lexical scopes.\n\n## The DOM Renderer: `leptos_dom`\n\nThe reactive system can be used to drive any kinds of side effects. One very\ncommon side effect is calling an imperative method, for example to update the\nDOM.\n\nThe entire DOM renderer is built on top of the reactive system. It provides\na builder pattern that can be used to create DOM elements dynamically.\n\nThe renderer assumes, as a convention, that dynamic attributes, classes,\nstyles, and children are defined by being passed a `Fn() -> T`, where their\nstatic equivalents just receive `T`. There’s nothing about this that is\ndivinely ordained, but it’s a useful convention because it allows us to use\nzero-overhead derived signals as one of several ways to indicate dynamic\ncontent.\n\n`leptos_dom` also contains code for server-side rendering of the same\nUI views to HTML, either for out-of-order streaming (`src/ssr.rs`) or\nin-order streaming/async rendering (`src/ssr_in_order.rs`).\n\n## The Macros: `leptos_macro`\n\nIt’s entirely possible to write Leptos code with no macros at all. The\n`view` and `component` macros, the most common, can be replaced by\nthe builder syntax and simple functions (see the `counter_without_macros`\nexample). But the macros enable a JSX-like syntax for describing views.\n\nThis package also contains the `Params` derive macro used for typed\nqueries and route params in the router.\n\n### Macro-based Optimizations\n\nLeptos 0.0.x was built much more heavily on macros. Taking its cues  \nfrom SolidJS, the `view` macro emitted different code for CSR, SSR, and\nhydration, optimizing each. The CSR/hydrate versions worked by compiling\nthe view to an HTML template string, cloning that `<template>`, and\ntraversing the DOM to set up reactivity. The SSR version worked similarly\nby compiling the static parts of the view to strings at compile time,\nreducing the amount of work that needed to be done on each request.\n\nProc macros are hard, and this system was brittle. 0.1 introduced a\nmore robust renderer, including the builder syntax, and rebuilt the `view`\nmacro to use that builder syntax instead. It moved the optimized-but-buggy\nCSR version of the macro to a more-limited `template` macro.\n\nThe `view` macro now separately optimizes SSR to use the same static-string\noptimizations, which (by our benchmarks) makes Leptos about 3-4x faster\nthan similar Rust frontend frameworks in its HTML rendering.\n\n> The optimization is pretty straightforward. Consider the following view:\n>\n> ```rust\n> view! { cx,\n>   <main class=\"text-center\">\n>     <div class=\"flex-col\">\n>       <button>\"Click me.\"</button>\n>       <p class=\"italic\">\"Text.\"</p>\n>     </div>\n>   </main>\n> }\n> ```\n>\n> Internally, with the builder this is something like\n>\n> ```rust\n> Element {\n>   tag: \"main\",\n>   attrs: vec![(\"class\", \"text-center\")],\n>   children: vec![\n> \t  Element {\n> \t\ttag: \"div\",\n> \t\tattrs: vec![(\"class\", \"flex-col\")],\n>       children: vec![\n>         Element {\n> \t        tag: \"button\",\n> \t\t\tattrs: vec![],\n> \t\t\tchildren: vec![\"Click me\"]\n>         },\n>         Element {\n> \t        tag: \"p\",\n> \t\t\tattrs: vec![(\"class\", \"italic\")],\n> \t\t\tchildren: vec![\"Text\"]\n>         }\n>       ]\n> \t  }\n>   ]\n> }\n> ```\n>\n> This is a _bunch_ of small allocations and separate strings,\n> and in early 0.1 versions we used a `SmallVec` for children and\n> attributes and actually caused some stack overflows.\n>\n> But if you look at the view itself you can see that none of this\n> will _ever_ change. So we can actually optimize it at compile\n> time to a single `&'static str`:\n>\n> ```rust\n> r#\"<main class=\"text-center\">\n>     <div class=\"flex-col\">\n>       <button>\"Click me.\"</button>\n>       <p class=\"italic\">\"Text.\"</p>\n>     </div>\n>   </main>\"#\n> ```\n\n## Server Functions (`leptos_server`, `server_fn`, and `server_fn_macro`)\n\nServer functions are a framework-agnostic shorthand for converting\na function, whose body can only be run on the server, into an ad hoc\nREST API endpoint, and then generating code on the client to call that\nendpoint when you call the function.\n\nThese are inspired by Solid/Bling’s `server$` functions, and there’s\nsimilar work being done in a number of other JavaScript frameworks.\n\nRPC is not a new idea, but these kinds of server functions may be.\nSpecifically, by using web standards (defaulting to `POST`/`GET` requests\nwith URL-encoded form data) they allow easy graceful degradation and the\nuse of the `<form>` element.\n\nThis function is split across three packages so that `server_fn` and\n`server_fn_macro` can be used by other frameworks. `leptos_server`\nincludes some Leptos-specific reactive functionality (like actions).\n\n## `leptos`\n\nThis package is built on and reexports most of the layers already\nmentioned, and implements a number of control-flow components (`<Show/>`,\n`<ErrorBoundary/>`, `<For/>`, `<Suspense/>`, `<Transition/>`) that use\npublic APIs of the other packages.\n\nThis is the main entrypoint for users, but is relatively light itself.\n\n## `leptos_meta`\n\nThis package exists to allow you to work with tags normally found in\nthe `<head>`, from within your components.\n\nIt is implemented as a distinct package, rather than part of\n`leptos_dom`, on the principle that “what can be implemented in userland,\nshould be.” The framework can be used without it, so it’s not in core.\n\n## `leptos_router`\n\nThe router originates as a direct port of `solid-router`, which is the\norigin of most of its terminology, architecture, and route-matching logic.\n\nSubsequent developments (like animated routing, and managing route transitions\ngiven the lack of `useTransition` in Leptos) have caused it to diverge\nslightly from Solid’s exact code, but it is still very closely related.\n\nThe core principle here is “nested routing,” dividing a single page\ninto independently-rendered parts. This is described in some detail in the docs.\n\nLike `leptos_meta`, it is implemented as a distinct package, because it\ncan be replaced with another router or with none. The framework can be used\nwithout it, so it’s not in core.\n\n## Server Integrations\n\nThe server integrations are the most “frameworky” layer of the whole framework.\nThese **do** assume the use of `leptos`, `leptos_router`, and `leptos_meta`.\nThey specifically draw routing data from `leptos_router`, and inject the\nmetadata from `leptos_meta` into the `<head>` appropriately.\n\nBut of course, if you one day create `leptos-helmet` and `leptos-better-router`,\nyou can create new server integrations that plug them into the SSR rendering\nmethods from `leptos_dom` instead. Everything involved is quite modular.\n\nThese packages essentially provide helpers that save the templates and user apps\nfrom including a huge amount of boilerplate to connect the various other packages\ncorrectly. Again, early versions of the framework examples are illustrative here\nfor reference: they include large amounts of manual SSR route handling, etc.\n\n## `cargo-leptos` helpers\n\n`leptos_config` and `leptos_hot_reload` exist to support two different features\nof `cargo-leptos`, namely its configuration and its view-patching/hot-reloading \nfeatures.\n\nIt’s important to say that the main feature `cargo-leptos` remains its ability\nto conveniently tie together different build tooling, compiling your app to\nWASM for the browser, building the server version, pulling in SASS and\nTailwind, etc. It is an extremely good build tool, not a magic formula. Each\nof the examples includes instructions for how to run the examples without\n`cargo-leptos`.\n"},"files":{"ARCHITECTURE.md":"# Architecture\n\nThe goal of this document is to make it easier for contributors (and anyone\nwho’s interested!) to understand the architecture of the framework.\n\nThe whole Leptos framework is built from a series of layers. Each of these layers\ndepends on the one below it, but each can be used independently from the ones\nbuilt on top of it. While running a command like `cargo leptos new --git \nleptos-rs/start` pulls in the whole framework, it’s important to remember that\nnone of this is magic: each layer of that onion can be stripped away and\nreimplemented, configured, or adapted as needed, incrementally.\n\n> Everything that follows will assume you have a good working understanding\n> of the framework. There will be explanations of how some parts of it work\n> or fit together, but these are not docs. They assume you know what I’m\n> talking about.\n\n## The Reactive System: `leptos_reactive`\n\nThe reactive system allows you to define dynamic values (signals),\nthe relationships between them (derived signals and memos), and the side effects\nthat run in response to them (effects).\n\nThese concepts are completely independent of the DOM and can be used to drive\nany kind of reactive updates. The reactive system is based on the assumption\nthat data is relatively cheap, and side effects are relatively expensive. Its\ngoal is to minimize those side effects (like updating the DOM or making a network\nrequests) as infrequently as possible.\n\nThe reactive system is implemented as a single data structure that exists at\nruntime. In exchange for giving ownership over a value to the reactive system\n(by creating a signal), you receive a `Copy + 'static` identifier for its\nlocation in the reactive system. This enables most of the ergonomics of storing\nand sharing state, the use of callback closures without lifetime issues, etc.\nThis is implemented by storing signals in a slotmap arena. The signal, memo,\nand scope types that are exposed to users simply carry around an index into that\nslotmap.\n\n> Items owned by the reactive system are dropped when the corresponding reactive\n> scope is dropped, i.e., when the component or section of the UI they’re\n> created in is removed. In a sense, Leptos implements a “garbage collector”\n> in which the lifetime of data is tied to the lifetime of the UI, not Rust’s\n> lexical scopes.\n\n## The DOM Renderer: `leptos_dom`\n\nThe reactive system can be used to drive any kinds of side effects. One very\ncommon side effect is calling an imperative method, for example to update the\nDOM.\n\nThe entire DOM renderer is built on top of the reactive system. It provides\na builder pattern that can be used to create DOM elements dynamically.\n\nThe renderer assumes, as a convention, that dynamic attributes, classes,\nstyles, and children are defined by being passed a `Fn() -> T`, where their\nstatic equivalents just receive `T`. There’s nothing about this that is\ndivinely ordained, but it’s a useful convention because it allows us to use\nzero-overhead derived signals as one of several ways to indicate dynamic\ncontent.\n\n`leptos_dom` also contains code for server-side rendering of the same\nUI views to HTML, either for out-of-order streaming (`src/ssr.rs`) or\nin-order streaming/async rendering (`src/ssr_in_order.rs`).\n\n## The Macros: `leptos_macro`\n\nIt’s entirely possible to write Leptos code with no macros at all. The\n`view` and `component` macros, the most common, can be replaced by\nthe builder syntax and simple functions (see the `counter_without_macros`\nexample). But the macros enable a JSX-like syntax for describing views.\n\nThis package also contains the `Params` derive macro used for typed\nqueries and route params in the router.\n\n### Macro-based Optimizations\n\nLeptos 0.0.x was built much more heavily on macros. Taking its cues  \nfrom SolidJS, the `view` macro emitted different code for CSR, SSR, and\nhydration, optimizing each. The CSR/hydrate versions worked by compiling\nthe view to an HTML template string, cloning that `<template>`, and\ntraversing the DOM to set up reactivity. The SSR version worked similarly\nby compiling the static parts of the view to strings at compile time,\nreducing the amount of work that needed to be done on each request.\n\nProc macros are hard, and this system was brittle. 0.1 introduced a\nmore robust renderer, including the builder syntax, and rebuilt the `view`\nmacro to use that builder syntax instead. It moved the optimized-but-buggy\nCSR version of the macro to a more-limited `template` macro.\n\nThe `view` macro now separately optimizes SSR to use the same static-string\noptimizations, which (by our benchmarks) makes Leptos about 3-4x faster\nthan similar Rust frontend frameworks in its HTML rendering.\n\n> The optimization is pretty straightforward. Consider the following view:\n>\n> ```rust\n> view! { cx,\n>   <main class=\"text-center\">\n>     <div class=\"flex-col\">\n>       <button>\"Click me.\"</button>\n>       <p class=\"italic\">\"Text.\"</p>\n>     </div>\n>   </main>\n> }\n> ```\n>\n> Internally, with the builder this is something like\n>\n> ```rust\n> Element {\n>   tag: \"main\",\n>   attrs: vec![(\"class\", \"text-center\")],\n>   children: vec![\n> \t  Element {\n> \t\ttag: \"div\",\n> \t\tattrs: vec![(\"class\", \"flex-col\")],\n>       children: vec![\n>         Element {\n> \t        tag: \"button\",\n> \t\t\tattrs: vec![],\n> \t\t\tchildren: vec![\"Click me\"]\n>         },\n>         Element {\n> \t        tag: \"p\",\n> \t\t\tattrs: vec![(\"class\", \"italic\")],\n> \t\t\tchildren: vec![\"Text\"]\n>         }\n>       ]\n> \t  }\n>   ]\n> }\n> ```\n>\n> This is a _bunch_ of small allocations and separate strings,\n> and in early 0.1 versions we used a `SmallVec` for children and\n> attributes and actually caused some stack overflows.\n>\n> But if you look at the view itself you can see that none of this\n> will _ever_ change. So we can actually optimize it at compile\n> time to a single `&'static str`:\n>\n> ```rust\n> r#\"<main class=\"text-center\">\n>     <div class=\"flex-col\">\n>       <button>\"Click me.\"</button>\n>       <p class=\"italic\">\"Text.\"</p>\n>     </div>\n>   </main>\"#\n> ```\n\n## Server Functions (`leptos_server`, `server_fn`, and `server_fn_macro`)\n\nServer functions are a framework-agnostic shorthand for converting\na function, whose body can only be run on the server, into an ad hoc\nREST API endpoint, and then generating code on the client to call that\nendpoint when you call the function.\n\nThese are inspired by Solid/Bling’s `server$` functions, and there’s\nsimilar work being done in a number of other JavaScript frameworks.\n\nRPC is not a new idea, but these kinds of server functions may be.\nSpecifically, by using web standards (defaulting to `POST`/`GET` requests\nwith URL-encoded form data) they allow easy graceful degradation and the\nuse of the `<form>` element.\n\nThis function is split across three packages so that `server_fn` and\n`server_fn_macro` can be used by other frameworks. `leptos_server`\nincludes some Leptos-specific reactive functionality (like actions).\n\n## `leptos`\n\nThis package is built on and reexports most of the layers already\nmentioned, and implements a number of control-flow components (`<Show/>`,\n`<ErrorBoundary/>`, `<For/>`, `<Suspense/>`, `<Transition/>`) that use\npublic APIs of the other packages.\n\nThis is the main entrypoint for users, but is relatively light itself.\n\n## `leptos_meta`\n\nThis package exists to allow you to work with tags normally found in\nthe `<head>`, from within your components.\n\nIt is implemented as a distinct package, rather than part of\n`leptos_dom`, on the principle that “what can be implemented in userland,\nshould be.” The framework can be used without it, so it’s not in core.\n\n## `leptos_router`\n\nThe router originates as a direct port of `solid-router`, which is the\norigin of most of its terminology, architecture, and route-matching logic.\n\nSubsequent developments (like animated routing, and managing route transitions\ngiven the lack of `useTransition` in Leptos) have caused it to diverge\nslightly from Solid’s exact code, but it is still very closely related.\n\nThe core principle here is “nested routing,” dividing a single page\ninto independently-rendered parts. This is described in some detail in the docs.\n\nLike `leptos_meta`, it is implemented as a distinct package, because it\ncan be replaced with another router or with none. The framework can be used\nwithout it, so it’s not in core.\n\n## Server Integrations\n\nThe server integrations are the most “frameworky” layer of the whole framework.\nThese **do** assume the use of `leptos`, `leptos_router`, and `leptos_meta`.\nThey specifically draw routing data from `leptos_router`, and inject the\nmetadata from `leptos_meta` into the `<head>` appropriately.\n\nBut of course, if you one day create `leptos-helmet` and `leptos-better-router`,\nyou can create new server integrations that plug them into the SSR rendering\nmethods from `leptos_dom` instead. Everything involved is quite modular.\n\nThese packages essentially provide helpers that save the templates and user apps\nfrom including a huge amount of boilerplate to connect the various other packages\ncorrectly. Again, early versions of the framework examples are illustrative here\nfor reference: they include large amounts of manual SSR route handling, etc.\n\n## `cargo-leptos` helpers\n\n`leptos_config` and `leptos_hot_reload` exist to support two different features\nof `cargo-leptos`, namely its configuration and its view-patching/hot-reloading \nfeatures.\n\nIt’s important to say that the main feature `cargo-leptos` remains its ability\nto conveniently tie together different build tooling, compiling your app to\nWASM for the browser, building the server version, pulling in SASS and\nTailwind, etc. It is an extremely good build tool, not a magic formula. Each\nof the examples includes instructions for how to run the examples without\n`cargo-leptos`.\n"},"items":[{"name":"ARCHITECTURE.md","path":"ARCHITECTURE.md","rawUrl":"https://raw.githubusercontent.com/leptos-rs/leptos/HEAD/ARCHITECTURE.md","title":"System Architecture & Module Boundaries","category":"project-spec","format":"markdown","content":"# Architecture\n\nThe goal of this document is to make it easier for contributors (and anyone\nwho’s interested!) to understand the architecture of the framework.\n\nThe whole Leptos framework is built from a series of layers. Each of these layers\ndepends on the one below it, but each can be used independently from the ones\nbuilt on top of it. While running a command like `cargo leptos new --git \nleptos-rs/start` pulls in the whole framework, it’s important to remember that\nnone of this is magic: each layer of that onion can be stripped away and\nreimplemented, configured, or adapted as needed, incrementally.\n\n> Everything that follows will assume you have a good working understanding\n> of the framework. There will be explanations of how some parts of it work\n> or fit together, but these are not docs. They assume you know what I’m\n> talking about.\n\n## The Reactive System: `leptos_reactive`\n\nThe reactive system allows you to define dynamic values (signals),\nthe relationships between them (derived signals and memos), and the side effects\nthat run in response to them (effects).\n\nThese concepts are completely independent of the DOM and can be used to drive\nany kind of reactive updates. The reactive system is based on the assumption\nthat data is relatively cheap, and side effects are relatively expensive. Its\ngoal is to minimize those side effects (like updating the DOM or making a network\nrequests) as infrequently as possible.\n\nThe reactive system is implemented as a single data structure that exists at\nruntime. In exchange for giving ownership over a value to the reactive system\n(by creating a signal), you receive a `Copy + 'static` identifier for its\nlocation in the reactive system. This enables most of the ergonomics of storing\nand sharing state, the use of callback closures without lifetime issues, etc.\nThis is implemented by storing signals in a slotmap arena. The signal, memo,\nand scope types that are exposed to users simply carry around an index into that\nslotmap.\n\n> Items owned by the reactive system are dropped when the corresponding reactive\n> scope is dropped, i.e., when the component or section of the UI they’re\n> created in is removed. In a sense, Leptos implements a “garbage collector”\n> in which the lifetime of data is tied to the lifetime of the UI, not Rust’s\n> lexical scopes.\n\n## The DOM Renderer: `leptos_dom`\n\nThe reactive system can be used to drive any kinds of side effects. One very\ncommon side effect is calling an imperative method, for example to update the\nDOM.\n\nThe entire DOM renderer is built on top of the reactive system. It provides\na builder pattern that can be used to create DOM elements dynamically.\n\nThe renderer assumes, as a convention, that dynamic attributes, classes,\nstyles, and children are defined by being passed a `Fn() -> T`, where their\nstatic equivalents just receive `T`. There’s nothing about this that is\ndivinely ordained, but it’s a useful convention because it allows us to use\nzero-overhead derived signals as one of several ways to indicate dynamic\ncontent.\n\n`leptos_dom` also contains code for server-side rendering of the same\nUI views to HTML, either for out-of-order streaming (`src/ssr.rs`) or\nin-order streaming/async rendering (`src/ssr_in_order.rs`).\n\n## The Macros: `leptos_macro`\n\nIt’s entirely possible to write Leptos code with no macros at all. The\n`view` and `component` macros, the most common, can be replaced by\nthe builder syntax and simple functions (see the `counter_without_macros`\nexample). But the macros enable a JSX-like syntax for describing views.\n\nThis package also contains the `Params` derive macro used for typed\nqueries and route params in the router.\n\n### Macro-based Optimizations\n\nLeptos 0.0.x was built much more heavily on macros. Taking its cues  \nfrom SolidJS, the `view` macro emitted different code for CSR, SSR, and\nhydration, optimizing each. The CSR/hydrate versions worked by compiling\nthe view to an HTML template string, cloning that `<template>`, and\ntraversing the DOM to set up reactivity. The SSR version worked similarly\nby compiling the static parts of the view to strings at compile time,\nreducing the amount of work that needed to be done on each request.\n\nProc macros are hard, and this system was brittle. 0.1 introduced a\nmore robust renderer, including the builder syntax, and rebuilt the `view`\nmacro to use that builder syntax instead. It moved the optimized-but-buggy\nCSR version of the macro to a more-limited `template` macro.\n\nThe `view` macro now separately optimizes SSR to use the same static-string\noptimizations, which (by our benchmarks) makes Leptos about 3-4x faster\nthan similar Rust frontend frameworks in its HTML rendering.\n\n> The optimization is pretty straightforward. Consider the following view:\n>\n> ```rust\n> view! { cx,\n>   <main class=\"text-center\">\n>     <div class=\"flex-col\">\n>       <button>\"Click me.\"</button>\n>       <p class=\"italic\">\"Text.\"</p>\n>     </div>\n>   </main>\n> }\n> ```\n>\n> Internally, with the builder this is something like\n>\n> ```rust\n> Element {\n>   tag: \"main\",\n>   attrs: vec![(\"class\", \"text-center\")],\n>   children: vec![\n> \t  Element {\n> \t\ttag: \"div\",\n> \t\tattrs: vec![(\"class\", \"flex-col\")],\n>       children: vec![\n>         Element {\n> \t        tag: \"button\",\n> \t\t\tattrs: vec![],\n> \t\t\tchildren: vec![\"Click me\"]\n>         },\n>         Element {\n> \t        tag: \"p\",\n> \t\t\tattrs: vec![(\"class\", \"italic\")],\n> \t\t\tchildren: vec![\"Text\"]\n>         }\n>       ]\n> \t  }\n>   ]\n> }\n> ```\n>\n> This is a _bunch_ of small allocations and separate strings,\n> and in early 0.1 versions we used a `SmallVec` for children and\n> attributes and actually caused some stack overflows.\n>\n> But if you look at the view itself you can see that none of this\n> will _ever_ change. So we can actually optimize it at compile\n> time to a single `&'static str`:\n>\n> ```rust\n> r#\"<main class=\"text-center\">\n>     <div class=\"flex-col\">\n>       <button>\"Click me.\"</button>\n>       <p class=\"italic\">\"Text.\"</p>\n>     </div>\n>   </main>\"#\n> ```\n\n## Server Functions (`leptos_server`, `server_fn`, and `server_fn_macro`)\n\nServer functions are a framework-agnostic shorthand for converting\na function, whose body can only be run on the server, into an ad hoc\nREST API endpoint, and then generating code on the client to call that\nendpoint when you call the function.\n\nThese are inspired by Solid/Bling’s `server$` functions, and there’s\nsimilar work being done in a number of other JavaScript frameworks.\n\nRPC is not a new idea, but these kinds of server functions may be.\nSpecifically, by using web standards (defaulting to `POST`/`GET` requests\nwith URL-encoded form data) they allow easy graceful degradation and the\nuse of the `<form>` element.\n\nThis function is split across three packages so that `server_fn` and\n`server_fn_macro` can be used by other frameworks. `leptos_server`\nincludes some Leptos-specific reactive functionality (like actions).\n\n## `leptos`\n\nThis package is built on and reexports most of the layers already\nmentioned, and implements a number of control-flow components (`<Show/>`,\n`<ErrorBoundary/>`, `<For/>`, `<Suspense/>`, `<Transition/>`) that use\npublic APIs of the other packages.\n\nThis is the main entrypoint for users, but is relatively light itself.\n\n## `leptos_meta`\n\nThis package exists to allow you to work with tags normally found in\nthe `<head>`, from within your components.\n\nIt is implemented as a distinct package, rather than part of\n`leptos_dom`, on the principle that “what can be implemented in userland,\nshould be.” The framework can be used without it, so it’s not in core.\n\n## `leptos_router`\n\nThe router originates as a direct port of `solid-router`, which is the\norigin of most of its terminology, architecture, and route-matching logic.\n\nSubsequent developments (like animated routing, and managing route transitions\ngiven the lack of `useTransition` in Leptos) have caused it to diverge\nslightly from Solid’s exact code, but it is still very closely related.\n\nThe core principle here is “nested routing,” dividing a single page\ninto independently-rendered parts. This is described in some detail in the docs.\n\nLike `leptos_meta`, it is implemented as a distinct package, because it\ncan be replaced with another router or with none. The framework can be used\nwithout it, so it’s not in core.\n\n## Server Integrations\n\nThe server integrations are the most “frameworky” layer of the whole framework.\nThese **do** assume the use of `leptos`, `leptos_router`, and `leptos_meta`.\nThey specifically draw routing data from `leptos_router`, and inject the\nmetadata from `leptos_meta` into the `<head>` appropriately.\n\nBut of course, if you one day create `leptos-helmet` and `leptos-better-router`,\nyou can create new server integrations that plug them into the SSR rendering\nmethods from `leptos_dom` instead. Everything involved is quite modular.\n\nThese packages essentially provide helpers that save the templates and user apps\nfrom including a huge amount of boilerplate to connect the various other packages\ncorrectly. Again, early versions of the framework examples are illustrative here\nfor reference: they include large amounts of manual SSR route handling, etc.\n\n## `cargo-leptos` helpers\n\n`leptos_config` and `leptos_hot_reload` exist to support two different features\nof `cargo-leptos`, namely its configuration and its view-patching/hot-reloading \nfeatures.\n\nIt’s important to say that the main feature `cargo-leptos` remains its ability\nto conveniently tie together different build tooling, compiling your app to\nWASM for the browser, building the server version, pulling in SASS and\nTailwind, etc. It is an extremely good build tool, not a magic formula. Each\nof the examples includes instructions for how to run the examples without\n`cargo-leptos`.\n","isInternal":false,"tokens":2293,"sizeBytes":9825}],"systemPromptSnippet":"<yakaai_skills repo=\"leptos-rs/leptos\">\n<!-- File: ARCHITECTURE.md (Tokens: ~2293 | Category: project-spec) -->\n# Architecture\n\nThe goal of this document is to make it easier for contributors (and anyone\nwho’s interested!) to understand the architecture of the framework.\n\nThe whole Leptos framework is built from a series of layers. Each of these layers\ndepends on the one below it, but each can be used independently from the ones\nbuilt on top of it. While running a command like `cargo leptos new --git \nleptos-rs/start` pulls in the whole framework, it’s important to remember that\nnone of this is magic: each layer of that onion can be stripped away and\nreimplemented, configured, or adapted as needed, incrementally.\n\n> Everything that follows will assume you have a good working understanding\n> of the framework. There will be explanations of how some parts of it work\n> or fit together, but these are not docs. They assume you know what I’m\n> talking about.\n\n## The Reactive System: `leptos_reactive`\n\nThe reactive system allows you to define dynamic values (signals),\nthe relationships between them (derived signals and memos), and the side effects\nthat run in response to them (effects).\n\nThese concepts are completely independent of the DOM and can be used to drive\nany kind of reactive updates. The reactive system is based on the assumption\nthat data is relatively cheap, and side effects are relatively expensive. Its\ngoal is to minimize those side effects (like updating the DOM or making a network\nrequests) as infrequently as possible.\n\nThe reactive system is implemented as a single data structure that exists at\nruntime. In exchange for giving ownership over a value to the reactive system\n(by creating a signal), you receive a `Copy + 'static` identifier for its\nlocation in the reactive system. This enables most of the ergonomics of storing\nand sharing state, the use of callback closures without lifetime issues, etc.\nThis is implemented by storing signals in a slotmap arena. The signal, memo,\nand scope types that are exposed to users simply carry around an index into that\nslotmap.\n\n> Items owned by the reactive system are dropped when the corresponding reactive\n> scope is dropped, i.e., when the component or section of the UI they’re\n> created in is removed. In a sense, Leptos implements a “garbage collector”\n> in which the lifetime of data is tied to the lifetime of the UI, not Rust’s\n> lexical scopes.\n\n## The DOM Renderer: `leptos_dom`\n\nThe reactive system can be used to drive any kinds of side effects. One very\ncommon side effect is calling an imperative method, for example to update the\nDOM.\n\nThe entire DOM renderer is built on top of the reactive system. It provides\na builder pattern that can be used to create DOM elements dynamically.\n\nThe renderer assumes, as a convention, that dynamic attributes, classes,\nstyles, and children are defined by being passed a `Fn() -> T`, where their\nstatic equivalents just receive `T`. There’s nothing about this that is\ndivinely ordained, but it’s a useful convention because it allows us to use\nzero-overhead derived signals as one of several ways to indicate dynamic\ncontent.\n\n`leptos_dom` also contains code for server-side rendering of the same\nUI views to HTML, either for out-of-order streaming (`src/ssr.rs`) or\nin-order streaming/async rendering (`src/ssr_in_order.rs`).\n\n## The Macros: `leptos_macro`\n\nIt’s entirely possible to write Leptos code with no macros at all. The\n`view` and `component` macros, the most common, can be replaced by\nthe builder syntax and simple functions (see the `counter_without_macros`\nexample). But the macros enable a JSX-like syntax for describing views.\n\nThis package also contains the `Params` derive macro used for typed\nqueries and route params in the router.\n\n### Macro-based Optimizations\n\nLeptos 0.0.x was built much more heavily on macros. Taking its cues  \nfrom SolidJS, the `view` macro emitted different code for CSR, SSR, and\nhydration, optimizing each. The CSR/hydrate versions worked by compiling\nthe view to an HTML template string, cloning that `<template>`, and\ntraversing the DOM to set up reactivity. The SSR version worked similarly\nby compiling the static parts of the view to strings at compile time,\nreducing the amount of work that needed to be done on each request.\n\nProc macros are hard, and this system was brittle. 0.1 introduced a\nmore robust renderer, including the builder syntax, and rebuilt the `view`\nmacro to use that builder syntax instead. It moved the optimized-but-buggy\nCSR version of the macro to a more-limited `template` macro.\n\nThe `view` macro now separately optimizes SSR to use the same static-string\noptimizations, which (by our benchmarks) makes Leptos about 3-4x faster\nthan similar Rust frontend frameworks in its HTML rendering.\n\n> The optimization is pretty straightforward. Consider the following view:\n>\n> ```rust\n> view! { cx,\n>   <main class=\"text-center\">\n>     <div class=\"flex-col\">\n>       <button>\"Click me.\"</button>\n>       <p class=\"italic\">\"Text.\"</p>\n>     </div>\n>   </main>\n> }\n> ```\n>\n> Internally, with the builder this is something like\n>\n> ```rust\n> Element {\n>   tag: \"main\",\n>   attrs: vec![(\"class\", \"text-center\")],\n>   children: vec![\n> \t  Element {\n> \t\ttag: \"div\",\n> \t\tattrs: vec![(\"class\", \"flex-col\")],\n>       children: vec![\n>         Element {\n> \t        tag: \"button\",\n> \t\t\tattrs: vec![],\n> \t\t\tchildren: vec![\"Click me\"]\n>         },\n>         Element {\n> \t        tag: \"p\",\n> \t\t\tattrs: vec![(\"class\", \"italic\")],\n> \t\t\tchildren: vec![\"Text\"]\n>         }\n>       ]\n> \t  }\n>   ]\n> }\n> ```\n>\n> This is a _bunch_ of small allocations and separate strings,\n> and in early 0.1 versions we used a `SmallVec` for children and\n> attributes and actually caused some stack overflows.\n>\n> But if you look at the view itself you can see that none of this\n> will _ever_ change. So we can actually optimize it at compile\n> time to a single `&'static str`:\n>\n> ```rust\n> r#\"<main class=\"text-center\">\n>     <div class=\"flex-col\">\n>       <button>\"Click me.\"</button>\n>       <p class=\"italic\">\"Text.\"</p>\n>     </div>\n>   </main>\"#\n> ```\n\n## Server Functions (`leptos_server`, `server_fn`, and `server_fn_macro`)\n\nServer functions are a framework-agnostic shorthand for converting\na function, whose body can only be run on the server, into an ad hoc\nREST API endpoint, and then generating code on the client to call that\nendpoint when you call the function.\n\nThese are inspired by Solid/Bling’s `server$` functions, and there’s\nsimilar work being done in a number of other JavaScript frameworks.\n\nRPC is not a new idea, but these kinds of server functions may be.\nSpecifically, by using web standards (defaulting to `POST`/`GET` requests\nwith URL-encoded form data) they allow easy graceful degradation and the\nuse of the `<form>` element.\n\nThis function is split across three packages so that `server_fn` and\n`server_fn_macro` can be used by other frameworks. `leptos_server`\nincludes some Leptos-specific reactive functionality (like actions).\n\n## `leptos`\n\nThis package is built on and reexports most of the layers already\nmentioned, and implements a number of control-flow components (`<Show/>`,\n`<ErrorBoundary/>`, `<For/>`, `<Suspense/>`, `<Transition/>`) that use\npublic APIs of the other packages.\n\nThis is the main entrypoint for users, but is relatively light itself.\n\n## `leptos_meta`\n\nThis package exists to allow you to work with tags normally found in\nthe `<head>`, from within your components.\n\nIt is implemented as a distinct package, rather than part of\n`leptos_dom`, on the principle that “what can be implemented in userland,\nshould be.” The framework can be used without it, so it’s not in core.\n\n## `leptos_router`\n\nThe router originates as a direct port of `solid-router`, which is the\norigin of most of its terminology, architecture, and route-matching logic.\n\nSubsequent developments (like animated routing, and managing route transitions\ngiven the lack of `useTransition` in Leptos) have caused it to diverge\nslightly from Solid’s exact code, but it is still very closely related.\n\nThe core principle here is “nested routing,” dividing a single page\ninto independently-rendered parts. This is described in some detail in the docs.\n\nLike `leptos_meta`, it is implemented as a distinct package, because it\ncan be replaced with another router or with none. The framework can be used\nwithout it, so it’s not in core.\n\n## Server Integrations\n\nThe server integrations are the most “frameworky” layer of the whole framework.\nThese **do** assume the use of `leptos`, `leptos_router`, and `leptos_meta`.\nThey specifically draw routing data from `leptos_router`, and inject the\nmetadata from `leptos_meta` into the `<head>` appropriately.\n\nBut of course, if you one day create `leptos-helmet` and `leptos-better-router`,\nyou can create new server integrations that plug them into the SSR rendering\nmethods from `leptos_dom` instead. Everything involved is quite modular.\n\nThese packages essentially provide helpers that save the templates and user apps\nfrom including a huge amount of boilerplate to connect the various other packages\ncorrectly. Again, early versions of the framework examples are illustrative here\nfor reference: they include large amounts of manual SSR route handling, etc.\n\n## `cargo-leptos` helpers\n\n`leptos_config` and `leptos_hot_reload` exist to support two different features\nof `cargo-leptos`, namely its configuration and its view-patching/hot-reloading \nfeatures.\n\nIt’s important to say that the main feature `cargo-leptos` remains its ability\nto conveniently tie together different build tooling, compiling your app to\nWASM for the browser, building the server version, pulling in SASS and\nTailwind, etc. It is an extremely good build tool, not a magic formula. Each\nof the examples includes instructions for how to run the examples without\n`cargo-leptos`.\n</yakaai_skills>"}