diff --git a/docs/pages/api-development-strategy.md b/docs/pages/api-development-strategy.md deleted file mode 100644 index 25cbdc29b88..00000000000 --- a/docs/pages/api-development-strategy.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: API Development Strategy -description: Remix's strategy to provide a smooth upgrade experience for application developers ---- - -# API Development Strategy - -Let's cut to the chase - major version upgrades can be a _pain_. Especially for something as foundational to your application as the framework or router it's built on. For Remix and React Router, we want to do our best to give you the smoothest upgrade experience possible. - -This strategy is discussed in more detail in our [Future Flags][future-flags-blog-post] blog post, so give that a read if you want any more info at the end of this doc! - -## Goals - -Our goals for major Remix and React Router releases are: - -- Developers can opt-into SemVer-major features individually _as they are released_ instead of having to wait to adopt them all at once when a new major version hits NPM -- Having opted into features ahead-of-time, developers can upgrade to new major versions in a single short-lived branch/commit (hours, not weeks) - -## Implementation - -We plan to do this via what we're calling **Future Flags** in the `remix.config.js` file. Think of these as **feature flags for future features**. As we implement new features, we always try to do them in a backwards-compatible way. But when a breaking change is warranted, we don't table that feature up for an _eventual_ release in the next major version. Instead, we add a **Future Flag** and implement the new feature alongside the current behavior in a minor release. This allows users to start using the feature, providing feedback, and reporting bugs _immediately_. - -That way, not only can you adopt features incrementally (and eagerly without a major version bump), we can also work out any kinks incrementally _before_ the next major release. Eventually we also then add deprecation warnings to the current major version to nudge users to the new behavior. Then in next major release we remove the old behavior, remove the deprecations, and remove the flag - thus making the flagged behavior the new default. If at the time the next major version is released, an application has opted into _all_ future flags and updated their code - then they should just be able to update their Remix dependencies to the latest version and delete the future flags from their `remix.config.js` and be running in a matter of minutes. - -## Unstable vs. Versioned Flags - -Future flags come in 2 forms: - -**`future.unstable_feature`** - -`unstable_` flags allow us to iterate on the API with early adopters as if we're in `v0.x.x` versions, but for a specific feature. This avoids churning the API for all users and arriving at better APIs in the final release. This _does not mean_ that we think the feature is bug-ridden! We _absolutely_ want early adopters to start using these features so we can iterate on (and/or gain confidence in) the API. - -**`future.vX_feature`** - -`vX_` (where `X` is the next major version) indicates a breaking change from current behavior and implies (1) that the API is considered stable and will not under any more breaking changes and (2) that the API will become the default behavior in the next major release. A `vX_` flag _does not_ mean the feature is bug-free - no software is! Our recommendation is to upgrade to versioned flags as you have the time, as it will make your next major upgrade _much_ smoother. - -### Example New Feature Flow - -The decision flow for a new feature looks something like this: - -![Flowchart of the decision process for how to introduce a new feature][feature-flowchart] - -The lifecycle is thus either: - -- Non-Breaking + Stable API Feature -> Lands directly in current major -- Non-Breaking + Unstable API -> `future.unstable_` flag in current major -> Lands in current major -- Breaking + Stable API Feature -> `future.vX_` flag in current major -> Default behavior in next major -- Breaking + Unstable API -> `future.unstable_` flag in current major -> `future.vX_` flag in current major -> Default behavior in next major - -[future-flags-blog-post]: https://remix.run/blog/future-flags -[feature-flowchart]: /docs-images/feature-flowchart.png diff --git a/docs/start/community.md b/docs/start/community.md new file mode 100644 index 00000000000..a66c2179b2b --- /dev/null +++ b/docs/start/community.md @@ -0,0 +1,45 @@ +--- +title: Community +description: Community resources for learning Remix and related technologies +order: 5 +--- + +# Community + +We work hard to keep the Remix community a friendly place where people want to hang out, help, and be helped. We're all here just trying to build great websites and make the web better. + +To that end, please keep in mind [our code of conduct][our-code-of-conduct]. + +- [Remix Discord][remix-discord-server] - A great place to have conversations, ask and answer questions, all about Remix. + +- [GitHub Discussions][git-hub-discussions-forum] - This is the best place to propose changes to Remix. The team uses it to gauge interest and understand use cases. + +- [Remix Twitter][twitter] - Tips, updates, and news about Remix from the team. + +- [Examples][the-examples-repository] - Dozens of Remix examples from the team and community. + +- [Remix Conf][remix-conf] - A yearly conference all about Remix with talks primarily from the community. + +- [Remix Mailing List][official-remix-team-mailing-list] - Not-so-regular email from the Remix team letting you know what the team is up to. + +- [Meetups][the-remix-meetup-page] - There are Remix Meetups all over the world with thousands of members. Some online, some in person, and some a hybrid of the two. + +- [Remix Guide][remix-guide] - A wonderful community site that gathers together everything that's going on in the Remix ecosystem: online courses, blog posts, app templates, events and more. + +- [Moulton][moulton] - Community Remix newsletter + +- [Releases on GitHub][releases-on-git-hub] - Not a bad idea to subscribe to Remix releases so you know what's coming. + +[our-code-of-conduct]: https://github.com/remix-run/remix/blob/main/CODE_OF_CONDUCT.md +[remix-discord-server]: https://rmx.as/discord +[git-hub-discussions-forum]: https://github.com/remix-run/remix/discussions +[the-examples-repository]: https://github.com/remix-run/examples +[official-remix-team-mailing-list]: https://remix.run/newsletter +[moulton]: https://www.readmoulton.com +[releases-on-git-hub]: https://github.com/remix-run/remix/releases +[official]: ../tutorials/blog +[tutorials]: ../tutorials/jokes +[remix-conf]: /conf +[the-remix-meetup-page]: https://rmx.as/meetup +[remix-guide]: https://remix.guide +[twitter]: https://twitter.com/remix_run diff --git a/docs/start/development.md b/docs/start/development.md new file mode 100644 index 00000000000..b47ba368de8 --- /dev/null +++ b/docs/start/development.md @@ -0,0 +1,29 @@ +--- +title: API Development Strategy +--- + +# API Development Strategy + +Our goals for major releases are: + +- Developers can opt-in to new features and changes individually as they are released _in the current major version_ instead of everything all at once in a new major release. +- Having opted-in to features ahead-of-time, developers can upgrade to new major versions without making changes to application code. + +## Unstable APIs and Future Flags + +New features are introduced with `unstable_feature` flags and API prefixes. + +- This allows us to iterate on the API with early adopters with breaking changes between minor releases while the API is marked unstable. +- It avoids churning the API for all users and arriving at better APIs in the stable releases. +- When an unstable feature is ready, the prefix is removed and the feature is shipped in the next minor release. The API will no longer change between minor releases. + +If you are using `unstable_*` future flags or APIs, it's important to check the release notes of every minor release because the behavior or API could change. It's also important to gives us feedback so we can make it better before the final release! + +## Breaking Changes and Future Flags + +Breaking changes are introduced in the current major version behind a future flag. If we are on `v2` then a breaking future flag would be something like `v3_somethingDifferent`. + +- Both versions work in parallel: the current `v2` behavior as well as the new `v3_somethingDifferent` behavior. +- This allows apps to update one change at a time in the current major release, instead of everything all at once in the next major release. Update on your schedule. +- If you have all `v3_*` future flags enabled, then upgrading to `v3` when it is released shouldn't require any changes to your code. +- Some breaking future flags start as `unstable_*` flags and may change between minor releases. After they become `v3_*` future flags the API should no longer change. diff --git a/docs/start/index.md b/docs/start/index.md new file mode 100644 index 00000000000..7f67f577077 --- /dev/null +++ b/docs/start/index.md @@ -0,0 +1,4 @@ +--- +title: Getting Started +order: 1 +--- diff --git a/docs/start/quickstart.md b/docs/start/quickstart.md new file mode 100644 index 00000000000..3542a497572 --- /dev/null +++ b/docs/start/quickstart.md @@ -0,0 +1,272 @@ +--- +title: Quick Start (5m) +order: 2 +--- + +# Quick Start + +This guide will get you familiar with the basic plumbing required to run a Remix app as quickly as possible. While there are many starter templates with different runtimes, deploy targets, and databases, we're going to create a bare-bones project from scratch. + +When you're ready to get serious about your Remix project, you might consider starting with a community template. They include typescript setups, databases, testing harnesses, authentication, and more. You can find a list of community templates on the [Remix Guide Templates][templates] page. + +## Installation + +```shellscript nonumber +$ mkdir my-remix-app +$ cd my-remix-app + +# install runtime dependencies +$ npm i @remix-run/node @remix-run/serve @remix-run/react react react-dom + +# install dev dependencies +$ npm i -D @remix-run/dev +``` + +Make sure to update package.json to indicate this project uses es modules: + +```json filename=package.json +{ + "type": "module" + // ... +} +``` + +## The Root Route + +```shellscript nonumber +$ mkdir app +$ touch app/root.jsx +``` + +`app/root.jsx` is what we call the "Root Route". It's the root layout of your entire app. Here's the basic set of elements you'll need for any project: + +```jsx +import { + Meta, + Links, + Scripts, + Outlet, +} from "@remix-run/react"; + +export default function Root() { + return ( + + + + + + + +

Hello world!

+ + + + + + ); +} +``` + +## Build and Run + +First build the app for production: + +```shellscript nonumber +$ remix build +``` + +You should now see a `build/` folder (the server version of your app) and `public/build` folder (the browser version) with some build artifacts in them. (This is all [configurable][remixconfig].) + +πŸ‘‰ **Run the app with `remix-serve`** + +```shellscript nonumber +# note the dash! +$ remix-serve build +``` + +You should be able to open up [http://localhost:3000](http://localhost:3000) and see the "hello world" page. + +Aside from the unholy amount of code in node_modules, our Remix app is just one file: + +``` +β”œβ”€β”€ app +β”‚ └── root.jsx +└── package.json +``` + +## Bring Your Own Server + +The `build/` directory created by `remix build` is just a module that you run inside of a server like Express, Cloudflare Workers, Netlify, Vercel, Fastly, AWS, Deno, Azure, Fastify, Firebase ... anywhere. + +If you don't care to set up your own server, you can use `remix-serve`. It's a simple express-based server maintained by the Remix team. However, Remix is specifically designed to run in _any_ JavaScript environment so that you own your stack. It is expected manyβ€”if not mostβ€”production apps will have their own server. You can read more about this in [Runtimes, Adapters, and Stacks][runtimes]. + +Just for kicks, let's stop using `remix-serve` and use express instead. + +πŸ‘‰ **Install Express and the Remix Express adapter** + +```shellscript nonumber +$ npm i express @remix-run/express + +# not going to use this anymore +$ npm uninstall @remix-run/serve +``` + +πŸ‘‰ **Create an Express server** + +```shellscript nonumber +$ touch server.mjs +``` + +```js filename=server.mjs +import { createRequestHandler } from "@remix-run/express"; +import express from "express"; + +// notice that the result of `remix build` is "just a module" +import * as build from "./build/index.js"; + +const app = express(); +app.use(express.static("public")); + +// and your app is "just a request handler" +app.all("*", createRequestHandler({ build })); + +app.listen(3000, () => { + console.log("App listening on http://localhost:3000"); +}); +``` + +πŸ‘‰ **Run your app with express** + +```shellscript nonumber +$ node server.mjs +``` + +Now that you own your server, you can debug your app with whatever tooling your server has. For example, you can inspect your app with chrome devtools with the [Node.js inspect flag][inspect]: + +```shellscript nonumber +$ node --inspect server.mjs +``` + +## Development Workflow + +Instead of stopping, rebuilding, and starting your server all the time, you can run Remix in development. This enables instant feedback to changes in your app with React Refresh (Hot Module Replacement) and Remix Hot Data Revalidation. + +First add a dev command in package.json that will run `remix dev`: + +πŸ‘‰ **Add a "scripts" entry to package.json** + +```json lines=[3-5] +{ + "type": "module", + "scripts": { + "dev": "remix dev -c \"node server.mjs\"" + } + //... +} +``` + +This will start the Remix development server which will watch your files for changes and rebuild your app. The `-c` flag tell it how to start your actual application server. + +When files change, Remix will restart your server for you, but because you own your server, you also have to tell Remix when it has restarted so Remix can safely send the hot updates to the browser. + +πŸ‘‰ **Add `broadcastDevReady` to your server** + +```js filename=server.mjs lines=[1,14-16] +import { createRequestHandler } from "@remix-run/express"; +import { broadcastDevReady } from "@remix-run/node"; +import express from "express"; + +import * as build from "./build/index.js"; + +const app = express(); +app.use(express.static("public")); + +// and your app is "just a request handler" +app.all("*", createRequestHandler({ build })); + +app.listen(4000, () => { + if (process.env.NODE_ENV === "development") { + broadcastDevReady(build); + } + console.log("App listening on http://localhost:4000"); +}); +``` + +And finally, let's connect your UI in the browser to receive those broadcasts: + +```tsx filename=app/root.tsx lines=[6,25] +import { + Meta, + Links, + Scripts, + Outlet, + LiveReload, +} from "@remix-run/react"; + +export default function Root() { + return ( + + + + + + + +

Dope

+ + + + + + + ); +} +``` + +πŸ‘‰ **Start the dev server** + +```shellscript nonumber +npm run dev +``` + +Now you can work on your app with immediate feedback. Give it a shot, change the text in `root.jsx` and watch! + +## Controlling Server and Browser Entries + +There are default magic files Remix is using that most apps don't need to mess with, but if you want to customize Remix's entry points to the server and browser you can run `remix reveal` and they'll get dumped into your project. + +```shellscript nonumber +$ remix reveal +Entry file entry.client created at app/entry.client.tsx. +Entry file entry.server created at app/entry.server.tsx. +``` + +## Summary + +Congrats, you can add Remix to your resume! Summing things up, we've learned: + +- `remix build` and `remix dev` compile your app into two things: + - A request handler that you add to your own JavaScript server + - A pile of static assets in your public directory for the browser +- You can bring your own server with adapters to deploy anywhere. +- You can set up a development workflow with HMR built-in + +In general, Remix is a bit "guts out". A few minutes of boilerplate but now you own your stack. + +What's next? + +- [Tutorial][tutorial] + +[fetch]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API +[runtimes]: ../book/01-runtimes +[inspect]: https://nodejs.org/en/docs/guides/debugging-getting-started/ +[tutorial]: ./tutorial +[book]: ../book/00-introduction +[remixconfig]: ../file-conventions/remix-config +[templates]: https://remix.guide/templates diff --git a/docs/tutorials/contacts.md b/docs/start/tutorial.md similarity index 99% rename from docs/tutorials/contacts.md rename to docs/start/tutorial.md index ce1a4d10d06..e58888b0312 100644 --- a/docs/tutorials/contacts.md +++ b/docs/start/tutorial.md @@ -1,9 +1,9 @@ --- -title: Simple App (30m) -order: 1 +title: Tutorial (30m) +order: 3 --- -# Simple App Tutorial +# Remix Tutorial We'll be building a small, but feature-rich app that lets you keep track of your contacts. There's no database or other "production ready" things so we can stay focused on Remix. We expect it to take about 30m if you're following along, otherwise it's a quick read. Check the other tutorials for more in-depth examples. diff --git a/docs/start/upgrading-from-react-router.md b/docs/start/upgrading-from-react-router.md new file mode 100644 index 00000000000..9b7fbf9ae7f --- /dev/null +++ b/docs/start/upgrading-from-react-router.md @@ -0,0 +1,7 @@ +--- +title: Upgrading from React Router +order: 4 +hidden: true +--- + +# Upgrading from React Router diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 583407c04a5..e73c7761ba1 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -1,4 +1,4 @@ --- title: Tutorials -order: 1 +hidden: true --- diff --git a/docs/tutorials/jokes.md b/docs/tutorials/jokes.md index 0b4dea2b5bc..164aace787c 100644 --- a/docs/tutorials/jokes.md +++ b/docs/tutorials/jokes.md @@ -1,6 +1,7 @@ --- title: App Tutorial (long) order: 4 +hidden: true --- # Jokes App Tutorial