Coder Social home page Coder Social logo

reactjs / react.dev Goto Github PK

View Code? Open in Web Editor NEW
11.0K 11.0K 7.5K 170.47 MB

The React documentation website

Home Page: https://react.dev/

License: Creative Commons Attribution 4.0 International

JavaScript 31.92% CSS 7.19% HTML 0.27% TypeScript 60.61% Shell 0.01%
documentation javascript react website

react.dev's Introduction

react.dev

This repo contains the source code and documentation powering react.dev.

Getting started

Prerequisites

  1. Git
  2. Node: any 12.x version starting with v12.0.0 or greater
  3. Yarn: See Yarn website for installation instructions
  4. A fork of the repo (for any contributions)
  5. A clone of the react.dev repo on your local machine

Installation

  1. cd react.dev to go into the project root
  2. yarn to install the website's npm dependencies

Running locally

  1. yarn dev to start the development server (powered by Next.js)
  2. open http://localhost:3000 to open the site in your favorite browser

Contributing

Guidelines

The documentation is divided into several sections with a different tone and purpose. If you plan to write more than a few sentences, you might find it helpful to get familiar with the contributing guidelines for the appropriate sections.

Create a branch

  1. git checkout main from any folder in your local react.dev repository
  2. git pull origin main to ensure you have the latest main code
  3. git checkout -b the-name-of-my-branch (replacing the-name-of-my-branch with a suitable name) to create a branch

Make the change

  1. Follow the "Running locally" instructions
  2. Save the files and check in the browser
  3. Changes to React components in src will hot-reload
  4. Changes to markdown files in content will hot-reload
  5. If working with plugins, you may need to remove the .cache directory and restart the server

Test the change

  1. If possible, test any visual changes in all latest versions of common browsers, on both desktop and mobile.
  2. Run yarn check-all. (This will run Prettier, ESLint and validate types.)

Push it

  1. git add -A && git commit -m "My message" (replacing My message with a commit message, such as Fix header logo on Android) to stage and commit your changes
  2. git push my-fork-name the-name-of-my-branch
  3. Go to the react.dev repo and you should see recently pushed branches.
  4. Follow GitHub's instructions.
  5. If possible, include screenshots of visual changes. A preview build is triggered after your changes are pushed to GitHub.

Translation

If you are interested in translating react.dev, please see the current translation efforts here.

License

Content submitted to react.dev is CC-BY-4.0 licensed, as found in the LICENSE-DOCS.md file.

react.dev's People

Contributors

acdlite avatar alexkrolick avatar arkist avatar bvaughn avatar chenglou avatar daniel15 avatar danilowoz avatar dependabot[bot] avatar dschau avatar eps1lon avatar gaearon avatar harish-sethuraman avatar jimfb avatar koba04 avatar kohei-takata avatar lex111 avatar marocchino avatar mcsheffrey avatar petehunt avatar poteto avatar rickhanlonii avatar robhrt7 avatar sebmarkbage avatar smikitky avatar sophiebits avatar tesseralis avatar vjeux avatar yangshun avatar zpao avatar zqran avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

react.dev's Issues

Incomplete documentation on creating web components

This issue was originally reported by @LukasBombach via facebook/react/issues/10155

Text of original issue:

your documentation on creating web components with react is quite cool and works really nice for the html. However, any component created this way will be unstyled as the documentation does not cover how to add CSS to the web component. Using create-react-app all your CSS will end up in a main.hash.css file and have selectors for your components, but when you create a web component, you css must be encapsulated in the component as the the components DOM lives in the shadow root and is not stylable from outside.

It would be cool if you could show a way to account for this.

Hello World doc page not showing

I initially discovered this issue when clicking the link to the Hello World Doc found in issue #56 .

The issue entails that when you visit the hello world doc page via any method other than navigating to it through the sites internal link structure (i.e copy/paste the link into the address bar, click from external source like github issue) you will receive a blank page.

Looking at the markup via inspect element it appears everything has been loaded and rendered fine; eventually when selecting an element via inspect element the page will render.

From testing i have managed to replicate the issue on some other pages. Issue occurring on Chrome 61.0.3163.100, macOS Sierra. Have tried a hard refresh and also reviewed the console which shows no errors.

In theory clicking the following link should cause the issue to occur: https://reactjs.org/docs/hello-world.html

Online IDE in the documentation

Continuing the conversation on Twitter here: twitter.com/acemarke/status/913891217385168896.

I think it would be very beneficial for beginners to use CodeSandbox/Stackblitz/WebpackBin to start learning React. The environment is like a local code editor, which means that the user already gets familiar with the feel of a code editor. The user doesn't have to install any tooling, so you can start immediately. Also, whenever they want to continue offline they can easily click on 'Download'/'Export' to get a CRA version of the same application so they can work further on it.

I think we all agree that this would be beneficial, the question is how to approach this without confusing the user. Would be great to have a discussion on this here.

Add an official React FAQ to the docs

Note: I originally reported this in facebook/react#10740 . Please see that thread for prior discussion.

I wrote the Redux FAQ last year, and it's been pretty helpful for answering actual frequently asked questions. It'd be great if we could add a similar FAQ directly to the React docs.

Tim Arney already has a standalone "React FAQ" site at https://reactfaq.site/ that would be a great starting point for a lot of the material. My React/Redux links list is also a useful source of info in general.

I'm opening this up as a place to discuss possible formatting for a React FAQ, as well as possible topics and volunteers to help write it.

Some thoughts, based on things I've seen and suggestions from the original thread:

A lot of the FAQs I see aren't necessarily about React exactly, but they come up enough and are related enough to be worth trying to answer.

My initial suggestions:

  • A section on AJAX calls
    • How can I make a call? (Point to common libs)
    • Where do I make a call, constructor/cWM/cDM ?
  • A section on method binding necessity and approaches
  • Function passing and references
    • The difference between passing a reference to a function and calling it
    • How to pass a parameter to a function as a handler ( onClick={() => someFunc("someParam")} ) , which as an FAQ is "why is my function being called whenever I re-render?" because they're doing onClick={someFunc("someParam")}

Suggestions from @satiewaltz

Due to React's highly unopinionated nature: It'd be great to use it as a small reference to the different styles and approaches people have building React apps. From the component level all the way up to philosophies on architecture.

As well as help people that are new to React accomplish everyday tasks/get over pitfalls be imparted with the full understanding of what is going on behind the scenes.

Here are some ideas on questions that could be apart of a FAQ:

  • A section on styling and CSS:
    • What is the difference between inline styles and CSS?
      • What are ways to do JavaScript animation in React?
      • Can I build animations using React's setState()?
    • A section on common performance issues regarding state updates.
    • A section on state and setState():
      • What setState() does exactly?
      • How do I do ordered state updates?
      • What is the difference between passing an object or a function in setState()?
    • A section on architecture:
      (It doesn't need to be comprehensive. Acts as an outline of recent developments the community has found when building with React over the years but without giving a side to a certain style):
      • Is there a recommended way to organize a React application's file structure? If not, what are some commonly used strategies?
      • How can I make the transition to React from other component libraries?
    • A section on React's internals:
      • What is the Virtual DOM? What Is the difference between it and the Shadow DOM?
      • What is React's new reconciliation algorithm in React 16?

In foresight to the answers to each FAQ in the future: It'd be best to be cautious of not pointing to one method as being particularly superior to another. Unless it's an anti-pattern of course. Due to the many numbers of ways one can build with React. And the differentiating costs and benefits each way can have. ("Common Anti-patterns" sounds like it could be a section of its own perhaps?) Though I could be entirely wrong about this thought of mine.

Wrong prettier version being used

While working on a PR, I noticed that when I ran yarn prettier prettier was applying formatting rules different from those in the .prettierrc config file (for example, Double Quotes instead of Single Quotes).

Upon closer inspection, I noticed that the wrong version of prettier was being used:

./node_modules/.bin/prettier --version
// 1.5.2

I think that the .prettierrc configuration file feature was introduced in version 1.6.0, so I think that's the reason the file is being completely ignored. When I run yarn prettier I also get this warning:
Ignored unknown option: --config

Document that you can't rely on React 16 SSR patching up differences

This issue was originally filed by @Tarnadas at facebook/react/issues/10591. There's a lot of interesting discussion there.

PR #116 added some additional clarity to the React 16 blog post by calling out that it's dangerous to have missing nodes on the server render, and they might get re-created with incorrect attributes.

@gaearon suggested in a comment below that a core team member should also create a more in-depth blog post about SSR behavior.

CI should run Lint, Flow, and Prettier checks for every PR

The package.json defines a check-all script that runs Prettier, Lint, and Flow. This script is intended to be run before commit to help catch inconsistent formatting or type errors. However we are not currently running this check as part of CI.

  • To fix this, first create a script that does the following (done via #93)
    • Run Prettier and fail if any modifications are made. (This means that the committed code isn't formatted correctly.)
    • Run ESLint and fail if there are any errors.
    • Run Flow and fail if there are any errors.
  • Fix all pre-existing errors so the new yarn ci-check task passes in master. (done via #104)
  • Hook this new script into CircleCI to run automatically for every PR. (A React team member will need to help with this step.) (done via #131)

Add clarity to Tutorial step 3

This issue was originally reported by @hori031617 via facebook/react/issues/10323

Text of original issue:

I tried tutorial.

  1. Delete all files in the src/ folder of the new project.

I think that good example code here.
For example rm -f src/*
Because, I had a misunderstanding remove src directory.

Thank you.

Document how React treats different attributes

This issue was originally reported by @MMeent via facebook/react/issues/9220

Please refer to the original issue for the related discussion thread.

Text of original issue:

As of #9106 there are quite a lot of tests for HTML's boolean properties on tags. According to these tests HTML properties should get rendered into empty strings or not set, e.g. <div hidden={true} /> should render to <div hidden="" /> and <div hidden={false} /> should render to <div />.

But when I look further, there are other tests which do similar things: <a href={true} /> should render to <a href="true" />. This means that if I take true as my property value, I will not know what the result will be.

The issue being: React currently does not have a clearly-defined and documented way with which they handle their props. Could the docs be updated to specify which type of prop will result in what? e.g. "any number gets parsed to a string (using Number.toString()), an object gets stringified by using arg => Object.entries(arg).map(([key, val]) => ${key}: ${val};).join(), and booleans toggle the property."

In short, these are the bugs/undocumented features/contradictions that the tests expect to happen, plus my expectations:

  • prop={true} gets parsed to prop="" or prop="true" for select properties
    expected: either prop="" or prop="prop", not both // as per checked=checked HTML standard
  • prop="" gets parsed as prop="" or
    expected: prop=""
  • prop="prop" might get parsed as either prop="prop", prop="" or even
    expected: prop="prop"
  • prop="foo" => prop="" or prop="foo"
    expected: prop="foo"
  • prop={false} => or prop="false"
    expected:
  • prop={['foo', 'bar']} => prop="" or prop="foo,bar" (hand-tested, no automatic test available)
    expected: prop="foo bar"
  • prop={{foo: 'bar', baz: 5}} => prop="" or prop="foo: bar; baz: 5;" or prop="[object Object]" (hand-tested, no automatic test available)
    expected: prop="foo: bar; baz: 5" // as per style object transform

Hacky showcase: https://jsfiddle.net/ox8a7vfe/3/

Are these features or are these bugs?

If they are bugs, and work is going to be done on the props value parsing, then the following might be a nice addition:

  • prop={{foo: true, bar: true, baz: false}} => prop="foo bar" // render all true keys, disregard false keys, like classNames.

Website displays empty page when cookies are disabled in Firefox

When using a Firefox with "Cookie Whitelist" plugin (and enabled, preventing cookie storage), loading https://reactjs.org/ flashes the page's content then removes all content in the body, producing an empty white page with the following content:

<body>
  <div id="___gatsby">
  </div>
</body>

When loading the page the content initially loads, flashes, and then a security exception is thrown in the console and all content is removed from the page:

DOMException [SecurityError: "The operation is insecure."
code: 18
nsresult: 0x80530012
location: https://reactjs.org/commons-2034d1df9ebd047740fd.js:4]

If the "Cookie Whitelist" is set to allow temporary cookies, the page loads normally.

Copied from facebook/react/issues/11015

Document how to pass args to event handlers

This issue was originally reported by @StokeMasterJack via facebook/react/issues/9685

A similar issue was reported by @Frazer via facebook/react/issues/8065

Text of original issue #9685

Inside a loop it is common to want to pass a param to an event handler:

<button onClick={(event) => this.deleteRow(23)}>Delete Row</button>
<button onClick={this.deleteRow.bind(this,23)}>Delete Row</button>

That would be a good thing to add to this doc page:

https://facebook.github.io/react/docs/handling-events.html

Also, how to pass args without triggering a re-render in the child component (i.e. creating a new function every time).

Add Flow types to website source

Replace PropTypes with Flow types for our components in www (and make sure yarn flow checks these types to protect against regressions).

I got the ball rolling with commit 1de4c66

This Twitter thread also has some interesting discussion for auto-generating Flow types for Gatsby's graphql queries.

Host codemods on the website

It would be nice to provide a REPL for React codemods on the website, particular for ones like
createClass or PropTypes. This would be handy for one-offs like converting StackOverflow answers or fiddles and would also introduce people to the idea of codemodding in a playful way. The REPL could also include instructions for how to run the codemods on the command line.

These codemods live in reactjs/react-codemod and are published to NPM under the name react-codemod. Seems like we could add the NPM module to the website's dependencies and then embed a few of them into a new REPL component.

Restructure docs to provide "paths" for guidance?

Originally repoted by @markerikson via facebook/react/issues/10991.
Please read the discussion thread on the original issue before beginning work on this one.

Per Dan's recent comments at https://news.ycombinator.com/item?id=15367044 and https://twitter.com/dan_abramov/status/913896989842137091 , a lot of people still seem to have complaints about the way the docs are structured.

It might be worth trying to restructure the docs kind of like a "Choose Your Own Adventure" book, with different "paths" based on what you know so far and what you want to accomplish (suggestions for reference: https://twitter.com/autiomaa/status/913908358662574083 , https://twitter.com/trevorbrindlejs/status/913907697602433025 ).

Hypothetical paths example:

What are you looking for?

  • I want to see if I'm ready to learn React - what should I know first?
    • links to a page discussing common JS prerequisite knowledge
  • I want to try out React right now , without installing anything:
    • links to a page that points to CodePen, CodeSandbox, and StackBlitz for online playgrounds, and also gives a copy-paste HTML snippet with links to CDN libs that the user can save and edit locally
  • I want to learn the basic ideas of React, with nothing "new" involved
    • links to a page that describes components and rendering, with ES5 syntax, without using JSX
  • I want to learn the recommended way to use React
    • links to a page that talks about Create-React-App, ES6+, and JSX syntax
  • I understand the basics - how do I learn to "think in React" as I build something?
    • probably links to the current tutorial section
  • I'm trying to build an application - how do I solve "real-world" problems with React?
    • links to a page that addresses topics like routing, state management, etc, like the guides discussed in #8060
  • I'm looking for advanced React usage patterns that can help me reuse code better
    • links to a page that covers topics like HOCs, render props, context, etc

Another related idea would be if the code samples in the docs all had multiple syntax variations that could be viewed by switching tabs or a global option across the site, like "Plain ES5 Syntax" / "ES6 and JSX Syntax" / "ES6+ Syntax".

Is there a way to disable outside scroll when scrolling in the live editor

In the Live JSX editor, when you scroll to the bottom of the code and continue scrolling, the whole page actually gets scrolled, which is annoying because right at this time you are focusing on the content of the editor, but the scrolling page may make you lose your concentration and unable to find where you were looking at.

image

Add ES5 example to Tutorial

This issue was originally reported by @quadruplejump via facebook/react/issues/10147

Text of original issue:

The tutorials, with the exception of the "advanced guides", assume ES6/JSX.

The React without ES6 tutorial https://facebook.github.io/react/docs/react-without-es6.html still uses JSX.

The React without JSX tutorial https://facebook.github.io/react/docs/react-without-jsx.html still uses ES6.

What would a simple ES5 React demo look like?

To compare, the Vue introduction https://vuejs.org/v2/guide/ starts with very simple examples that you can just drop in a webpage.

Note from Dan

We can probably add an intro paragraph to both of these pages that links to HTML page with minimal example.

Note from Brian

Pending the outcome of #122, it might be nice to host the new minimal example in the repo and display it in CodeSandbox/Codepen.

Missing documentation: null/undefined as input valu

Originally filed by @DanielSWolf via facebook/react/issues/11031

Do you want to request a feature or report a bug?

I'd like to request documentation. :-)

When you pass null as value of an input, you get the following warning:

warning.js:33 Warning: value prop on select should not be null. Consider using the empty string to clear the component or undefined for uncontrolled components.

This warning very clearly states what to do. My problem is, it fails to mention why I'm not supposed to pass null. Nor could I find any explanation online:

Naively, I'd expect null to be a perfectly valid value, e.g. for a numeric input that is empty. Passing an empty string to indicate the absence of a numeric value seems odd to me. So I'd really like some more information in the documentation!

Maintain scroll position of mobile menus

Originally reported by @KyleAMathews via facebook/react/issues/10952

When going quickly through pages on mobile, it'd be really nice if as you scroll down long menus e.g. in docs, if after navigating to the next page and then returning to the menu if the previous scroll position is maintained/restored.

This could be done by by storing the menu scroll position in the layout again and then passing it into the page component on render.

Add section headers to navigation element

This issue was originally opened by @donpinkus via facebook/react/issues/10980

The side-nav only displays page titles. It would be nice if it also displayed section headers for the current page:

screen shot 2017-09-29 at 3 53 48 pm

For example - what are the life cycle events in React? The closest thing in the nav is "Quick Start > State and Lifecycle". After navigating to this page, and reading for a few seconds - it becomes clear this is a tutorial. Is there a list of the lifecycle events? I'm not sure. I scan through the whole page. Doesn't look like it, but maybe I just missed it. Repeating this process of scrolling through entire pages is time consuming, so instead I just google "react 16 lifecycle events" and end up finding it on someone's independent blog post.

Improve/create documentation for ReactTestUtils.renderIntoDocument()

This issue was originally reported by @the-spyke via facebook/react/issues/10330

There is almost none documentation about how to actually use .renderIntoDocument() method. I can't find find answers on those questions on Jest's website or enzyme's (I know that it's not Facebook) either.

  • If I render a component into a DOM in a test, how will it be destroyed?
  • Should I clean up by myself?
  • What tools to use for this?
  • Just .unmountComponentAtNode()?
  • Where I will get the container to pass in?
  • What about additional component trees like in Popovers?
  • What are the best ways to test that there aren't any parts left after my component were unmounted?

It will be nice to see such information before people will met memory leaks in their tests, and also help to establish good practices for writing tests.

Additional notes:

  • Calling .renderIntoDocument() returns you an instance
  • This instance was rendered into freshly created DOM element, which now represents a detached tree
  • There's also a reference to the instance in ReactDOM's internal map
  • So, even if you remove all your references to this instance, on every call to .renderIntoDocument() you will get 1 detached tree hanging in memory + 1 instance of a React component with all its props not available for garbage collection

Document (non-)interaction between native and synthetic events

This issue was originally reported by @srittau as facebook/react/issues/10284

Text of the original issue:

I have been trying to find out why my React event handlers were not able to prevent event handlers on document. After hours of searching and experimenting, I stumbled across issue #7094, which explains it.

Unfortunately, the documentation at https://facebook.github.io/react/docs/handling-events.html gives the impression that React events work exactly like native events, apart from wrapping them in synthetic events, and could therefore interact with them. Please document that this is not the case.

The same applies to the documentation at https://facebook.github.io/react/docs/events.html, especially the first paragraph of the overview. A short remark on this page would be helpful as well.

Gracefully recover when ad block prevents Babel from loading

I've seen reports that certain ad blockers (eg Fair AdBlocker 1.404) prevent Babel from loading which causes a script error and results in the following:
screen shot 2017-10-09 at 9 55 10 am

We could detect this case (eg no Babel) and show an error message about ad blockers specifically, letting users know to whitelist reactjs.org if they want the live code examples to work.

Note that this issue is related to issue #2 and may be impacted by its implementation.

Add CI check for unique redirect URLs

@sophiebits and I recently noticed that /docs/index.html redirected to /docs/accessibility.html rather than /docs/hello-world.html. This turned out to be because both /docs/hello-word.md and /docs/accessibility.md declared the redirect rule redirect_from: "docs/index.html". (Presumably this is because one was copied from the other without much thought about the redirect bit.)

We should add a check to gatsby-node.js that throws an error if it detects a duplicate redirect. This will cause the Netlify preview to fail and alert a PR reviewer that there's a problem.

Documentation about which style numeric values are treated as pixels is missing

This change was originally requested by @Kovensky via facebook/react/issues/10418

This used to exist in the React 15 documentation under the Tips section, but mentions to this support are now missing entirely.

The old documentation page: https://github.com/facebook/react/blob/8cac523beaaacfeae179ca14a1d8a46d82892016/docs/tips/06-style-props-value-px.md

This was removed in commit 455d2d1b48e5cdaeac5d0b4fd92b29b4d52bcaec

Add error boundaries and exception tracking to the website

Part 1: Gracefully handle exceptions

If an error occurs, we should show some kind of fallback UI.

We already handle specific types of errors like failing to load Babel or Algolia libs from CDN, but a more general-purpose error boundary would be nice to handle other unexpected errors.

Part 2: Track exceptions

We should also log/track errors as well. Maybe we could use GA's exception tracking for this?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.