start a new react project

Author: Archmonger

README.md

@@ -15,6 +15,7 @@ In order to set up an environment to develop these docs...
 7. Follow the on-screen prompts to view the documentation in your browser
 8. You can now edit the markdown files located within `docs/src/` and see the changes in real time
 
-All unfinished tabs are marked via a construction symbol ( 🚧 ).
+🚧 : Unfinished tab
+🚫 : Tab is blocked from being started due to external factors 
 
 Feel free to PR this branch with any changes you make to the documentation. If you have any questions, feel free to ask in the [Discord server](https://discord.gg/uNb5P4hA9X).

docs/examples/python/start_a_new_react_project/configure_example.py

@@ -0,0 +1,6 @@
+from fastapi import FastAPI
+
+from reactpy.backend.fastapi import configure
+
+asgi_app = FastAPI()
+configure(asgi_app)

docs/src/learn/add-react-to-an-existing-project.md

@@ -1,7 +1,12 @@
 ---
-title: Add React to an Existing Project 🚧
+title: Add React to an Existing Project 🚫
 ---
 
+<!--
+TODO: Template tag is needed to complete this tab
+https://github.com/reactive-python/reactpy/issues/653
+-->
+
 ## Overview
 
 <p class="intro" markdown>

docs/src/learn/start-a-new-react-project.md

@@ -1,133 +1,154 @@
 ---
-title: Start a New React Project 🚧
+title: Start a New React Project
 ---
 
 ## Overview
 
 <p class="intro" markdown>
 
-If you want to build a new app or a new website fully with React, we recommend picking one of the React-powered frameworks popular in the community. Frameworks provide features that most apps and sites eventually need, including routing, data fetching, and generating HTML.
+If you want to build a new app or a new website fully with ReactPy, we recommend picking one of the ReactPy-compatible backends popular in the community. These backend frameworks provide features that most apps and sites eventually need, including routing, data fetching, and session management.
 
 </p>
 
-<Note>
 
-**You need to install [Node.js](https://nodejs.org/en/) for local development.** You can _also_ choose to use Node.js in production, but you don't have to. Many React frameworks support export to a static HTML/CSS/JS folder.
+## Built-in Backends
 
-</Note>
+<!-- FIXME: This is reliant on https://github.com/reactive-python/reactpy/issues/1071 -->
 
-## Production-grade React frameworks
+!!! note
 
-### Next.js
+    Some of our frameworks are considered _built-in_, meaning that compatibility for these backends are contained within `reactpy.backend.*`.
 
-**[Next.js](https://nextjs.org/) is a full-stack React framework.** It's versatile and lets you create React apps of any size--from a mostly static blog to a complex dynamic application. To create a new Next.js project, run in your terminal:
+    In order to run ReactPy with these frameworks, you will need to run `reactpy.backend.*.configure(...)` on your ASGI application. This command will configure the necessary settings and routes for ReactPy to work properly.
 
-<TerminalBlock>
-npx create-next-app
-</TerminalBlock>
+    For example, this is how you would configure ReactPy for FastAPI:
 
-If you're new to Next.js, check out the [Next.js tutorial.](https://nextjs.org/learn/foundations/about-nextjs)
+	```python linenums="0"
+	{% include "../../examples/python/start_a_new_react_project/configure_example.py" %}
+	```
 
-Next.js is maintained by [Vercel](https://vercel.com/). You can [deploy a Next.js app](https://nextjs.org/docs/deployment) to any Node.js or serverless hosting, or to your own server. [Fully static Next.js apps](https://nextjs.org/docs/advanced-features/static-html-export) can be deployed to any static hosting.
+### FastAPI
 
-### Remix
+FastAPI is a high-performance web framework that is designed for speed and efficiency. It is built on top of the asyncio library and uses a number of optimizations to achieve its performance. FastAPI is a good choice for web applications that need to be fast and scalable.
 
-**[Remix](https://remix.run/) is a full-stack React framework with nested routing.** It lets you break your app into nested parts that can load data in parallel and refresh in response to the user actions. To create a new Remix project, run:
+!!! example "Terminal"
 
-<TerminalBlock>
-npx create-remix
-</TerminalBlock>
+    ```bash linenums="0"
+    pip install reactpy[fastapi]
+    ```
 
-If you're new to Remix, check out the Remix [blog tutorial](https://remix.run/docs/en/main/tutorials/blog) (short) and [app tutorial](https://remix.run/docs/en/main/tutorials/jokes) (long).
+If you're new to FastAPI, check out the [FastAPI tutorial](https://fastapi.tiangolo.com/tutorial/).
 
-Remix is maintained by [Shopify](https://www.shopify.com/). When you create a Remix project, you need to [pick your deployment target](https://remix.run/docs/en/main/guides/deployment). You can deploy a Remix app to any Node.js or serverless hosting by using or writing an [adapter](https://remix.run/docs/en/main/other-api/adapter).
+You will need to [configure FastAPI](#built-in-backends) in order to use it with ReactPy.
 
-### Gatsby
+### Flask
 
-**[Gatsby](https://www.gatsbyjs.com/) is a React framework for fast CMS-backed websites.** Its rich plugin ecosystem and its GraphQL data layer simplify integrating content, APIs, and services into one website. To create a new Gatsby project, run:
+Flask is a microframework that is lightweight and easy to use. It is a good choice for small and simple web applications. Flask does not include many features out of the box, but it is highly customizable and can be extended with a variety of third-party libraries.
 
-<TerminalBlock>
-npx create-gatsby
-</TerminalBlock>
+!!! example "Terminal"
 
-If you're new to Gatsby, check out the [Gatsby tutorial.](https://www.gatsbyjs.com/docs/tutorial/)
+    ```bash linenums="0"
+    pip install reactpy[flask]
+    ```
 
-Gatsby is maintained by [Netlify](https://www.netlify.com/). You can [deploy a fully static Gatsby site](https://www.gatsbyjs.com/docs/how-to/previews-deploys-hosting) to any static hosting. If you opt into using server-only features, make sure your hosting provider supports them for Gatsby.
+If you're new to Flask, check out the [Flask tutorial](https://flask.palletsprojects.com/en/latest/tutorial/).
 
-### Expo (for native apps)
+You will need to [configure Flask](#built-in-backends) in order to use it with ReactPy.
 
-**[Expo](https://expo.dev/) is a React framework that lets you create universal Android, iOS, and web apps with truly native UIs.** It provides an SDK for [React Native](https://reactnative.dev/) that makes the native parts easier to use. To create a new Expo project, run:
+### Sanic
 
-<TerminalBlock>
-npx create-expo-app
-</TerminalBlock>
+Sanic is a microframework that is designed for speed and performance. It is built on top of the asyncio library and uses a number of optimizations to achieve its performance. Sanic is a good choice for web applications that need to be fast and scalable.
 
-If you're new to Expo, check out the [Expo tutorial](https://docs.expo.dev/tutorial/introduction/).
+!!! example "Terminal"
 
-Expo is maintained by [Expo (the company)](https://expo.dev/about). Building apps with Expo is free, and you can submit them to the Google and Apple app stores without restrictions. Expo additionally provides opt-in paid cloud services.
+    ```bash linenums="0"
+    pip install reactpy[sanic]
+    ```
 
-<DeepDive>
+If you're new to Sanic, check out the [Sanic tutorial](https://sanicframework.org/en/guide/).
 
-#### Can I use React without a framework?
+You will need to [configure Sanic](#built-in-backends) in order to use it with ReactPy.
 
-You can definitely use React without a framework--that's how you'd [use React for a part of your page.](/learn/add-react-to-an-existing-project#using-react-for-a-part-of-your-existing-page) **However, if you're building a new app or a site fully with React, we recommend using a framework.**
+### Starlette
 
-Here's why.
+Starlette is a lightweight framework that is designed for simplicity and flexibility. It is built on top of the ASGI standard and is very easy to extend. Starlette is a good choice for web applications that need to be simple and flexible.
 
-Even if you don't need routing or data fetching at first, you'll likely want to add some libraries for them. As your JavaScript bundle grows with every new feature, you might have to figure out how to split code for every route individually. As your data fetching needs get more complex, you are likely to encounter server-client network waterfalls that make your app feel very slow. As your audience includes more users with poor network conditions and low-end devices, you might need to generate HTML from your components to display content early--either on the server, or during the build time. Changing your setup to run some of your code on the server or during the build can be very tricky.
+!!! example "Terminal"
 
-**These problems are not React-specific. This is why Svelte has SvelteKit, Vue has Nuxt, and so on.** To solve these problems on your own, you'll need to integrate your bundler with your router and with your data fetching library. It's not hard to get an initial setup working, but there are a lot of subtleties involved in making an app that loads quickly even as it grows over time. You'll want to send down the minimal amount of app code but do so in a single client–server roundtrip, in parallel with any data required for the page. You'll likely want the page to be interactive before your JavaScript code even runs, to support progressive enhancement. You may want to generate a folder of fully static HTML files for your marketing pages that can be hosted anywhere and still work with JavaScript disabled. Building these capabilities yourself takes real work.
+    ```bash linenums="0"
+    pip install reactpy[starlette]
+    ```
 
-**React frameworks on this page solve problems like these by default, with no extra work from your side.** They let you start very lean and then scale your app with your needs. Each React framework has a community, so finding answers to questions and upgrading tooling is easier. Frameworks also give structure to your code, helping you and others retain context and skills between different projects. Conversely, with a custom setup it's easier to get stuck on unsupported dependency versions, and you'll essentially end up creating your own framework—albeit one with no community or upgrade path (and if it's anything like the ones we've made in the past, more haphazardly designed).
+If you're new to Starlette, check out the [Starlette tutorial](https://www.starlette.io/tutorial/).
 
-If you're still not convinced, or your app has unusual constraints not served well by these frameworks and you'd like to roll your own custom setup, we can't stop you--go for it! Grab `react` and `react-dom` from npm, set up your custom build process with a bundler like [Vite](https://vitejs.dev/) or [Parcel](https://parceljs.org/), and add other tools as you need them for routing, static generation or server-side rendering, and more. </DeepDive>
+You will need to [configure Starlette](#built-in-backends) in order to use it with ReactPy.
 
-## Bleeding-edge React frameworks
+### Tornado
 
-As we've explored how to continue improving React, we realized that integrating React more closely with frameworks (specifically, with routing, bundling, and server technologies) is our biggest opportunity to help React users build better apps. The Next.js team has agreed to collaborate with us in researching, developing, integrating, and testing framework-agnostic bleeding-edge React features like [React Server Components.](/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023#react-server-components)
+Tornado is a scalable web framework that is designed for high-traffic applications. It is built on top of the asyncio library and uses a number of optimizations to achieve its scalability. Tornado is a good choice for web applications that need to handle a lot of traffic.
 
-These features are getting closer to being production-ready every day, and we've been in talks with other bundler and framework developers about integrating them. Our hope is that in a year or two, all frameworks listed on this page will have full support for these features. (If you're a framework author interested in partnering with us to experiment with these features, please let us know!)
+!!! example "Terminal"
 
-### Next.js (App Router)
+    ```bash linenums="0"
+    pip install reactpy[tornado]
+    ```
 
-**[Next.js's App Router](https://beta.nextjs.org/docs/getting-started) is a redesign of the Next.js APIs aiming to fulfill the React team’s full-stack architecture vision.** It lets you fetch data in asynchronous components that run on the server or even during the build.
+If you're new to Tornado, check out the [Tornado tutorial](https://www.tornadoweb.org/en/stable/guide/).
 
-Next.js is maintained by [Vercel](https://vercel.com/). You can [deploy a Next.js app](https://nextjs.org/docs/deployment) to any Node.js or serverless hosting, or to your own server. Next.js also supports [static export](https://beta.nextjs.org/docs/configuring/static-export) which doesn't require a server. <Pitfall>
+You will need to [configure Tornado](#built-in-backends) in order to use it with ReactPy.
 
-Next.js's App Router is **currently in beta and is not yet recommended for production** (as of Mar 2023). To experiment with it in an existing Next.js project, [follow this incremental migration guide](https://beta.nextjs.org/docs/upgrade-guide#migrating-from-pages-to-app).
+## External Backends
 
-</Pitfall>
+### Django
 
-<DeepDive>
+[Django](https://www.djangoproject.com/) is a full-featured web framework that provides a batteries-included approach to web development. It includes features such as ORM, templating, authentication, and authorization. Django is a good choice for large and complex web applications.
 
-#### Which features make up the React team’s full-stack architecture vision?
+!!! example "Terminal"
 
-Next.js's App Router bundler fully implements the official [React Server Components specification](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md). This lets you mix build-time, server-only, and interactive components in a single React tree.
+    ```bash linenums="0"
+    pip install reactpy-django
+    ```
 
-For example, you can write a server-only React component as an `async` function that reads from a database or from a file. Then you can pass data down from it to your interactive components:
+If you're new to Django, check out the [Django tutorial](https://docs.djangoproject.com/en/dev/intro/tutorial01/).
 
-```js
-// This component runs *only* on the server (or during the build).
-async function Talks({ confId }) {
-	// 1. You're on the server, so you can talk to your data layer. API endpoint not required.
-	const talks = await db.Talks.findAll({ confId });
+You will need to [configure Django](https://reactive-python.github.io/reactpy-django/get-started/installation/) in order to use it with ReactPy.
 
-	// 2. Add any amount of rendering logic. It won't make your JavaScript bundle larger.
-	const videos = talks.map((talk) => talk.video);
+### Jupyter
 
-	// 3. Pass the data down to the components that will run in the browser.
-	return <SearchableVideoList videos={videos} />;
-}
-```
+Jupyter is an interactive computing environment that is used for data science and machine learning. It allows users to run code, visualize data, and collaborate with others in a live environment. Jupyter is a powerful tool for data scientists and machine learning engineers.
 
-Next.js's App Router also integrates [data fetching with Suspense](/blog/2022/03/29/react-v18#suspense-in-data-frameworks). This lets you specify a loading state (like a skeleton placeholder) for different parts of your user interface directly in your React tree:
+!!! example "Terminal"
 
-```js
-<Suspense fallback={<TalksLoading />}>
-	<Talks confId={conf.id} />
-</Suspense>
-```
+    ```bash linenums="0"
+    pip install reactpy-jupyter
+    ```
 
-Server Components and Suspense are React features rather than Next.js features. However, adopting them at the framework level requires buy-in and non-trivial implementation work. At the moment, the Next.js App Router is the most complete implementation. The React team is working with bundler developers to make these features easier to implement in the next generation of frameworks.
+If you're new to Jupyter, check out the [Jupyter tutorial](https://jupyter.org/try).
 
-</DeepDive>
+You will need to [configure Jupyter](https://github.com/reactive-python/reactpy-jupyter#readme) in order to use it with ReactPy.
+
+### Plotly Dash
+
+Plotly Dash is a web application framework that is used to create interactive dashboards. It allows users to create dashboards that can be used to visualize data and interact with it in real time. Plotly Dash is a good choice for creating dashboards that need to be interactive and informative.
+
+!!! example "Terminal"
+
+    ```bash linenums="0"
+    pip install reactpy-dash
+    ```
+
+If you're new to Plotly Dash, check out the [Plotly Dash tutorial](https://dash.plotly.com/installation).
+
+You will need to [configure Plotly Dash](https://github.com/reactive-python/reactpy-dash#readme) in order to use it with ReactPy.
+
+!!! info "Deep Dive"
+
+    <font size="4">**Can I use ReactPy without a backend framework?**</font>
+
+    You can not ReactPy without a backend—this project was designed to be built on-top of existing web frameworks. 
+
+    Here's why.
+
+    You can think of ReactPy as ReactJS server side rendering, but with a Python server. We rely on Python web frameworks and webservers in order to process ReactPy traffic. **This means that you can [use any Python web framework](../learn/creating-backends.md) as a ReactPy backend, as long as it supports the ASGI standard.** As your project grows with every new feature, you may want to switch backends in the future. As a result, we recommend keeping all backend-related logic within hook functions in order to make the "points of integration" between ReactPy and your backend as small as possible.
+	
+	**If you're building a new app or a site fully with ReactPy, we recommend using your favorite backend combined with [`reactpy-router`](https://github.com/reactive-python/reactpy-router) to create a Single Page Application (SPA).**