From 61e9afc232631e9fb6279076dbc594d57a401562 Mon Sep 17 00:00:00 2001 From: Dan Levy <397632+justsml@users.noreply.github.com> Date: Sun, 21 Oct 2018 14:41:10 -0600 Subject: [PATCH 1/8] Added simpler "basic" example --- .../docs/guides/quick-start.md | 117 ++++++++++-------- 1 file changed, 67 insertions(+), 50 deletions(-) diff --git a/packages/react-router-dom/docs/guides/quick-start.md b/packages/react-router-dom/docs/guides/quick-start.md index 2e36b82800..9f591e7f5b 100644 --- a/packages/react-router-dom/docs/guides/quick-start.md +++ b/packages/react-router-dom/docs/guides/quick-start.md @@ -21,79 +21,96 @@ yarn add react-router-dom npm install react-router-dom ``` -Now you can copy/paste any of the examples into `src/App.js`. Here's the -basic one: +## Examples + +Copy/paste either of the examples (below) into your `src/App.js`. + +### Example: Basic Routing + +In this example we have 3 'Page' Components handled by the ``. + +Note: Instead of `` we use ``. ```jsx import React from "react"; import { BrowserRouter as Router, Route, Link } from "react-router-dom"; +const Home = () =>

Home

; +const About = () =>

About

; +const Users = () =>

Users

; -const Home = () => ( -
-

Home

-
-); +const AppRouter = () => ( + +
+ + + + + -const About = () => ( -
-

About

-
+
+ ); -const Topic = ({ match }) => ( -
-

{match.params.topicId}

-
+export default AppRouter; +``` + +### Example: Nested Routing + +This example shows how nested routing works. The route `/topics` loads the `Topics` component, which resolves any further ``'s conditionally on the paths `:id`. + +```jsx +import React from "react"; +import { BrowserRouter as Router, Route, Link } from "react-router-dom"; + +const AppRouter = () => ( + +
+
+ + + + + +
+ ); +const Home = () =>

Home

; +const About = () =>

About

; +const Topic = ({ match }) =>

Requested Param: {match.params.id}

; const Topics = ({ match }) => (

Topics

+
    -
  • - Rendering with React -
    • -
  • - Components -
    • -
  • - Props v. State -
    • +
  • Components
    • +
  • Props v. State
- +

Please select a topic.

} + render={() =>

Please select a topic.

} /> +
); - -const BasicExample = () => ( - -
-
    -
  • - Home -
    • -
  • - About -
    • -
  • - Topics -
    • -
- -
- - - - -
- +const Header = () => ( +
    +
  • Home
    • +
  • About
    • +
  • Topics
    • +
); -export default BasicExample; + +export default AppRouter; ``` Now you're ready to tinker. Happy routing! From 7253cbd518879d101354ef6fc5afd6f9cceba0ff Mon Sep 17 00:00:00 2001 From: Dan Levy <397632+justsml@users.noreply.github.com> Date: Sun, 21 Oct 2018 14:45:56 -0600 Subject: [PATCH 2/8] Trying to make Quick Start the default contents "Philosophy" page is a bit too 'inside baseball' for an effective landing page. --- website/modules/docs/Web.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/modules/docs/Web.js b/website/modules/docs/Web.js index dbcdff94c7..8d5ec64f1a 100644 --- a/website/modules/docs/Web.js +++ b/website/modules/docs/Web.js @@ -19,9 +19,9 @@ export default { ], guides: [ + require("../../../packages/react-router-dom/docs/guides/quick-start.md"), require("../../../packages/react-router/docs/guides/philosophy.md"), require("../../../packages/react-router-dom/docs/guides/basic-components.md"), - require("../../../packages/react-router-dom/docs/guides/quick-start.md"), require("../../../packages/react-router-dom/docs/guides/server-rendering.md"), require("../../../packages/react-router-dom/docs/guides/code-splitting.md"), require("../../../packages/react-router-dom/docs/guides/scroll-restoration.md"), From 2b609a1a6205787d20c678385e73822b22ecda70 Mon Sep 17 00:00:00 2001 From: Dan Levy <397632+justsml@users.noreply.github.com> Date: Sun, 21 Oct 2018 14:46:40 -0600 Subject: [PATCH 3/8] Moved Philosophy down further --- website/modules/docs/Web.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/modules/docs/Web.js b/website/modules/docs/Web.js index 8d5ec64f1a..8b4df6ee7e 100644 --- a/website/modules/docs/Web.js +++ b/website/modules/docs/Web.js @@ -20,11 +20,11 @@ export default { guides: [ require("../../../packages/react-router-dom/docs/guides/quick-start.md"), - require("../../../packages/react-router/docs/guides/philosophy.md"), require("../../../packages/react-router-dom/docs/guides/basic-components.md"), require("../../../packages/react-router-dom/docs/guides/server-rendering.md"), require("../../../packages/react-router-dom/docs/guides/code-splitting.md"), require("../../../packages/react-router-dom/docs/guides/scroll-restoration.md"), + require("../../../packages/react-router/docs/guides/philosophy.md"), require("../../../packages/react-router/docs/guides/testing.md?web"), require("../../../packages/react-router/docs/guides/redux.md"), require("../../../packages/react-router/docs/guides/static-routes.md"), From f6fcdfd92236dfd8b95a3fe540ecafaf23bc013c Mon Sep 17 00:00:00 2001 From: Dan Levy <397632+justsml@users.noreply.github.com> Date: Sun, 21 Oct 2018 14:48:52 -0600 Subject: [PATCH 4/8] Added labels to 3rd party snippets --- packages/react-router/docs/guides/philosophy.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/react-router/docs/guides/philosophy.md b/packages/react-router/docs/guides/philosophy.md index 21dfe94533..162638dfa2 100644 --- a/packages/react-router/docs/guides/philosophy.md +++ b/packages/react-router/docs/guides/philosophy.md @@ -7,6 +7,7 @@ This guide's purpose is to explain the mental model to have when using React Rou If you've used Rails, Express, Ember, Angular etc. you've used static routing. In these frameworks, you declare your routes as part of your app's initialization before any rendering takes place. React Router pre-v4 was also static (mostly). Let's take a look at how to configure routes in express: ```js +// Express style routing: app.get("/", handleIndex); app.get("/invoices", handleInvoices); app.get("/invoices/:id", handleInvoice); @@ -18,6 +19,7 @@ app.listen(); Note how the routes are declared before the app listens. The client side routers we've used are similar. In Angular you declare your routes up front and then import them to the top-level `AppModule` before rendering: ```js +// Angular style routing: const appRoutes: Routes = [ { path: "crisis-center", @@ -54,6 +56,7 @@ imports into the application for you. Again, this happens before your app renders. ```js +// Ember Style Router: Router.map(function() { this.route("about"); this.route("contact"); From 5739c097fd986f0bf30cfc26ee184f232de4e7a4 Mon Sep 17 00:00:00 2001 From: Dan Levy <397632+justsml@users.noreply.github.com> Date: Sun, 21 Oct 2018 14:50:17 -0600 Subject: [PATCH 5/8] Minor formatting fix --- packages/react-router/docs/guides/philosophy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/react-router/docs/guides/philosophy.md b/packages/react-router/docs/guides/philosophy.md index 162638dfa2..486fb271e2 100644 --- a/packages/react-router/docs/guides/philosophy.md +++ b/packages/react-router/docs/guides/philosophy.md @@ -7,7 +7,7 @@ This guide's purpose is to explain the mental model to have when using React Rou If you've used Rails, Express, Ember, Angular etc. you've used static routing. In these frameworks, you declare your routes as part of your app's initialization before any rendering takes place. React Router pre-v4 was also static (mostly). Let's take a look at how to configure routes in express: ```js -// Express style routing: +// Express Style routing: app.get("/", handleIndex); app.get("/invoices", handleInvoices); app.get("/invoices/:id", handleInvoice); @@ -19,7 +19,7 @@ app.listen(); Note how the routes are declared before the app listens. The client side routers we've used are similar. In Angular you declare your routes up front and then import them to the top-level `AppModule` before rendering: ```js -// Angular style routing: +// Angular Style routing: const appRoutes: Routes = [ { path: "crisis-center", From 4f7f3d9cd2d440aa765842b0ce83bddbb96ded26 Mon Sep 17 00:00:00 2001 From: Dan Levy Date: Sun, 21 Oct 2018 17:36:50 -0600 Subject: [PATCH 6/8] fixing up quick start content --- .../docs/guides/quick-start.md | 67 +++++++++++-------- website/modules/docs/Native.js | 2 +- 2 files changed, 40 insertions(+), 29 deletions(-) diff --git a/packages/react-router-dom/docs/guides/quick-start.md b/packages/react-router-dom/docs/guides/quick-start.md index 9f591e7f5b..90169c205a 100644 --- a/packages/react-router-dom/docs/guides/quick-start.md +++ b/packages/react-router-dom/docs/guides/quick-start.md @@ -1,9 +1,10 @@ # Quick Start -The easiest way to get started with a React web project is with a tool called [Create React App][crapp], a Facebook project with a ton of community help. +You need a React web app to add `react-router`. -First install create-react-app if you don't already have it, and then -make a new project with it. +If you need to create one, the easiest way to get started is with a popular tool called [Create React App][crapp]. + +First install `create-react-app`, if you don't already have it, and then make a new project with it. ```sh npm install -g create-react-app @@ -13,27 +14,24 @@ cd demo-app ## Installation -React Router DOM is [published to npm](https://npm.im/react-router-dom) so you can install it with either `npm` or [`yarn`](https://yarnpkg.com). Create React App uses yarn, so that's what we'll use. +React Router DOM is [published to npm](https://npm.im/react-router-dom) so you can install it with either `npm` or [`yarn`](https://yarnpkg.com). ```sh -yarn add react-router-dom -# or, if you're not using yarn npm install react-router-dom ``` -## Examples - -Copy/paste either of the examples (below) into your `src/App.js`. +Copy/paste either of the examples (below) into your `src/App.js`. -### Example: Basic Routing +## Example: Basic Routing -In this example we have 3 'Page' Components handled by the ``. +In this example we have 3 'Page' Components handled by the ``. Note: Instead of `` we use ``. ```jsx import React from "react"; import { BrowserRouter as Router, Route, Link } from "react-router-dom"; + const Home = () =>

Home

; const About = () =>

About

; const Users = () =>

Users

; @@ -43,16 +41,21 @@ const AppRouter = () => (
-
); @@ -60,15 +63,15 @@ const AppRouter = () => ( export default AppRouter; ``` -### Example: Nested Routing +## Example: Nested Routing -This example shows how nested routing works. The route `/topics` loads the `Topics` component, which resolves any further ``'s conditionally on the paths `:id`. +This example shows how nested routing works. The route `/topics` loads the `Topics` component, which renders any further ``'s conditionally on the paths `:id` value. ```jsx import React from "react"; import { BrowserRouter as Router, Route, Link } from "react-router-dom"; -const AppRouter = () => ( +const App = () => (
@@ -76,7 +79,6 @@ const AppRouter = () => ( -
); @@ -87,30 +89,39 @@ const Topic = ({ match }) =>

Requested Param: {match.params.id}

; const Topics = ({ match }) => (

Topics

- +
    -
  • Components
    • -
  • Props v. State
    • +
  • + Components +
    • +
  • + Props v. State +

Please select a topic.

} + render={() =>

Please select a topic.

} /> -
); const Header = () => (
    -
  • Home
    • -
  • About
    • -
  • Topics
    • +
  • + Home +
    • +
  • + About +
    • +
  • + Topics +
); -export default AppRouter; +export default App; ``` Now you're ready to tinker. Happy routing! diff --git a/website/modules/docs/Native.js b/website/modules/docs/Native.js index 27f0153d9e..928cfde941 100644 --- a/website/modules/docs/Native.js +++ b/website/modules/docs/Native.js @@ -79,10 +79,10 @@ export default { } ], guides: [ - require("../../../packages/react-router/docs/guides/philosophy.md"), require("../../../packages/react-router-native/docs/guides/quick-start.md"), require("../../../packages/react-router-native/docs/guides/deep-linking.md"), require("../../../packages/react-router-native/docs/guides/animation.md"), + require("../../../packages/react-router/docs/guides/philosophy.md"), require("../../../packages/react-router/docs/guides/redux.md"), require("../../../packages/react-router/docs/guides/blocked-updates.md") ] From b3b2edd44c56c985a2571f20d0c9e5b75fcf33d0 Mon Sep 17 00:00:00 2001 From: Dan Levy Date: Sun, 21 Oct 2018 18:02:44 -0600 Subject: [PATCH 7/8] updating "quick start" content --- packages/react-router-dom/docs/guides/quick-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-router-dom/docs/guides/quick-start.md b/packages/react-router-dom/docs/guides/quick-start.md index 90169c205a..d0fa12055c 100644 --- a/packages/react-router-dom/docs/guides/quick-start.md +++ b/packages/react-router-dom/docs/guides/quick-start.md @@ -1,6 +1,6 @@ # Quick Start -You need a React web app to add `react-router`. +You'll need a React web app to add `react-router`. If you need to create one, the easiest way to get started is with a popular tool called [Create React App][crapp]. From bd57741825136a65063d0452ed63463431cd07de Mon Sep 17 00:00:00 2001 From: Dan Levy Date: Sun, 21 Oct 2018 18:08:10 -0600 Subject: [PATCH 8/8] a bit OCD formatting/alignment --- packages/react-router-dom/docs/guides/quick-start.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/react-router-dom/docs/guides/quick-start.md b/packages/react-router-dom/docs/guides/quick-start.md index d0fa12055c..7349190254 100644 --- a/packages/react-router-dom/docs/guides/quick-start.md +++ b/packages/react-router-dom/docs/guides/quick-start.md @@ -32,7 +32,7 @@ Note: Instead of `` we use ``. import React from "react"; import { BrowserRouter as Router, Route, Link } from "react-router-dom"; -const Home = () =>

Home

; +const Index = () =>

Home

; const About = () =>

About

; const Users = () =>

Users

; @@ -53,7 +53,7 @@ const AppRouter = () => ( - +