To add a bit of context: the React docs were previously a Jekyll site that was hosted at facebook.github.io/react/. The new site was rebuilt using Gatsby.js (a React-based static site generator), uses the Glamor CSS-in-JS library for styling, and has a bunch of nice tweaks and improvements overall, like the live component editors on the front page.
They might have had _something_ on the front page before, don't remember what exactly. I know they had CodePen examples added in the "Getting Started" and "Tutorial" sections when the docs content was rewritten last year. The use of the React-Live editor widget on the front is specifically new, I just don't remember if it replaced something similar previously.
I cannot overstate how nice it is to use. I built a sign-up page for a startup with it and I had absolutely no complaints.
Writing static content is basically like building a normal website with a nice templating system. Dynamic content is simply React components that I'm use to working with on complex applications.
Easy to build, easy to deploy, and easy to change.
Gatsby is great but it has issues generating sites with a large number of pages. There are performance issues and generation fails if the number of pages goes above a certain threshold.
I had to abandon it for a project that was generating static SEO pages, it was something on the order of 2000 pages and Gatsby couldn't handle it. Hopefully they resolve that soon!
I can see how you'd have that perception but the term covers a wide swath of use cases. Search engine spam is not nearly the issue it once was. Most SEO pages are created to account for two things: product marketing content cannot contain all the possible terms that people use when searching without becoming unintelligible and data served dynamically through SPAs, especially geographically localized data, is still challenging to expose to search engines even with universal apps.
Sorry to hear that! We're focusing on build performance and incremental site builds and will be releasing a major version bump by the end of the year to make the experience faster.
Glad to hear it! I think Gatsby is fantastic and I'm still looking for other projects to use it on. I love how unobtrusive the framework part of it is, feels like just writing a vanilla react/redux app. The GraphQL data layer is inspired!
Awesome! Yeah, that was our main design focus. Make it feel like you're building a vanilla React web app but make it as speedy as the fastest websites.
Apparently the latest React significantly improves server-side rendering, so it might be worth giving Gatsby a try again even just with the React package updated to the latest version (and I'd love to hear what the speed increase is).
I abandoned my own React-based SSG because it was slow, but I'm hoping to dust it off when I have some more time to see the effects.
Can you change the docs section dropdown interaction? When I go to look at the docs, it's really nice to be able to see everything instead of opening each major section one at a time (especially when opening one closes all the others).
Yeah, that's super annoying. I would think that a team that can build react could build a site with it that doesn't have FOUC. If they can't do it, what hope do the rest of us have?
And the page doesn't even come back from the flash in my semi-locked down firefox. It flashes content, then back to a white page without an empty <body>:
DOMException [SecurityError:"The operation is insecure." Code 18: location: https://reactjs.org/commons-f40206259909ee9b7a40.js:4]`
Looks like it's related to their use of TypeKit for fonts.
I haven't used TypeKit in a while, but it looks like they had this issue a year ago [1]. Unclear if it has been fixed or what. A lot of people I know simply embed the font in the page (ugh)
As an aside, I hate the official React tutorial and am disappointed that there are no revisions to it with this significant redesign and React version update. It is the embodiment of the “how to draw an owl” meme, requiring you to have a strong JS frontend background in the first place, and the resulting demo application doesn’t give much insight in how to use React for standard websites. (Unfortunately, this isn’t unique to the official React tutorial; many React tutorials are like this)
Contrast with the official Vue.js tutorial (https://vuejs.org/v2/guide/), which goes through things step by step with normal HTML syntax.
> We hope the new site will make it easier for you all to contribute improvements as well. We look forward to working with you to improve it! [1]
This was just the first phase of them moving to the new site. They understand that the docs can be better. Maybe instead of just complaining about them, you contribute to them to make them more "noob" friendly, like you are describing.
> requiring you to have a strong JS frontend background in the first place
Is that a high bar for a JS frontend framework? Serious question, as it doesn't seem that way to me. This seems analogous to saying "Django docs require you to know python" or "Postgres docs require you to understand how databases work".
I lost an entire week of work last year to not knowing that React switched from automatically binding methods, because none of the documents mentioned that. Including the release notes of the version of React where they turned that off, IIRC.
It is easily the most rage-inducing programmer moment I ever had, mainly because it's so fucking stupid and the only reason it took me so long was because the actual tutorial and documentation was fucking lying to me.
Technically speaking they fixed it by now: they mention the bind-thingy under "Handling Events" in the documentation, which you randomly have to stumble upon:
constructor(props) {
super(props);
this.state = {isToggleOn: true};
// This binding is necessary to make `this` work in the callback
this.handleClick = this.handleClick.bind(this);
}
handleClick() {
this.setState(prevState => ({
isToggleOn: !prevState.isToggleOn
}));
}
I think you might be mistaken. `React.createClass` always did autobinding, and it still does. The ES6 classes (which the tutorial now uses) never supported autobinding.
React documentation switched from `React.createClass` to ES6 classes because they community already did at that point, and wanted to see the more "mainstream" pattern documented. I'm sorry it wasn't obvious that there is a difference between the function call and the language syntax, but it's definitely not a change in React.
The tutorial you mention works fine because `onClick={() => this.handleClick(i)}` is an alternative way to bind methods that also works. That's what the tutorial uses because it's easier to explain React first without diving into how `this` works in ES6 classes. And you can run that code and verify it works. (Every step of the tutorial has a link with a code example.) So no, it has not been broken for a year.
React.createClass() always did (and still does) autobinding.
ES6 classes never supported autobinding.
We couldn't have changed your code from one to the other. There is no "release notes" associated with that change—changing the syntax was a conscious decision you made either when converting or when writing a new components.
While you're right that there was no breaking change, it isn't unreasonable for a developer to expect, when a feature is introduced that is analogous to an existing feature, that the new feature's differences will be explained.
If you already know about ES6 classes, what you say is obvious, I'm sure. Or if you're in a place where someone more experienced can teach you. Neither of those things applied to me. I had no prior webdev experience, used to languages where this does not behave like it does in JS, and relying on documentation to guide me.
It can be nearly impossible to Google something if you don't even know what it is that you don't know.
There's a comment by, well, YOU, from March this year[0] on a github issue discussing improvements to documentation, suggesting it is one of the most common troubleshooting issues, so I'm not the only idiot failing to grasp this when first diving into webdev.
It would help tremendously if there was even just a simple sentence in the tutorial like:
> "By the way, we are using an arrow function here because JavaScript has some subtle behaviour when it comes to this, but explaining the details of that here would take too long. See [here], [here] and [here]"
.. with a few links explaining both this and ES6 classes in more detail. Because otherwise you can easily get stuck not even knowing where to look for the cause of the bug.
I think you need to take some personal responsibility here for not knowing how Javascript works.
That you've written so much indicates to me that you expect other people (like a framework's documentation) to introduce you to every language idiosyncrasy in any place you happen to be reading.
That's not what I want people to expect from me as a professional. People should be able to expect me to credentialize in the domain at hand.
Still, it isn't entirely obvious under what conditions the methods of a React Component class are going to be called. For all you know they might always be called against the instance.
Would you like to send a PR? I don't mean to sound defensively, but I have spent a huge amount of effort on docs in the past, and as you can see they're still not good. :-) So some help from you (you know the pain points!) would be handy.
The subtlety that arrow functions are different would bite you anywhere in javascript, including vanilla. It should come up if you read the MDN documentation on this or arrow functions.
As the person who designed most of the tutorial, I'm sorry to hear this. My goal was to give people practice building a few simple components and connecting them together.
It's true that we assume preexisting JS knowledge, but your other point about how it doesn't give much insight into using React is one I haven't heard before. Can you say more about what you mean?
Anecdotally in my experience, most people seem to find the tutorial pretty helpful, but we can think about more options. Maybe there's space to add one that assumes less about JS. (And really -- thank you for complaining about this, or else we wouldn't have known.)
This is probably just me and feel free to disregard if this sounds silly, but I really wish miss the getting started guide from a few years ago that (iirc) had you drop an include statement in and go.
I feel like React expects me to have a deep knowledge of JS build tooling when all I care about getting started is building a page locally that works and does cool things.
FWIW this is how Vue's tutorial starts - and another really nice thing they do is teach you the API by entering things into your console on their tutorial page full of components.
I don't really know if this is constructive or useful, I hope it is - I just feel like React expects a lot of new users in a way it didn't used to.
Thanks! I agree the simplicity is compelling. Our Getting Started page does offer CDN script tags as an option but it's seemed like create-react-app is a better tool for most people getting started on a new app so we've had that more prominently.
The tutorial asks you to either use CodePen (which requires no build tooling) or Create React App (which requires you to run a command in the terminal but then you don't need to configure anything):
Similarly, the installation page offers you to either download a single HTML file, or to install a CLI that gives you a project that's ready to go: https://reactjs.org/docs/installation.html
Could you clarify what give you an impression that you need to have a deep knowledge of build tooling to follow along?
Hey Dan, I really appreciate you responding here - I know things like Create React App have come in the past couple years, and that people love it - I'm not trying to take anything away from what you've built. I know the way I learned React isn't how anybody is ever going to make anything production quality.
I'll try to clarify. If you don't mind another comparison to Vue, their equivalent page: https://vuejs.org/v2/guide/ says "Or, you can create an index.html file and include Vue with:
<script src="https://unpkg.com/vue"></script>", while your get started page says "If you’d rather use a local development environment, check out the Installation page." I know, if I click there it'll say I have an index.html and I know I shouldn't do it that way, but if I have none of the infrastructure on my computer and I want to build my thing on my computer, I'm looking for the script - not installation instructions.
On that 'how to follow along' page, under prerequisites it says "Note that we’re also using some features from ES6, a recent version of JavaScript. In this tutorial, we’re using arrow functions, classes, let, and const statements. You can use Babel REPL to check what ES6 code compiles to.". If this was the first React tutorial I ever looked at I'd be completely lost here and concluding I don't understand the prerequisites. If I know anything about 'relatively new' things in Javascript or Babel then I assume that I'm expected to use it somehow to actually use those relatively new things in my browser, but I have no idea how.
Also, scrolling down a bit, "if you prefer to write code in your editor" is a list of 6 steps, one of which is installing Node and another is "Follow the installation instructions to create a new project." I might not need deep knowledge, but this feels like a lot of stuff to do to follow a tutorial in my editor.
Here's my story about the old, do-it-all-locally tutorial: I'd just started an internship, and got a brief about doing some dynamic UI generation from schemas in .net stuff I'd never used, and was meant to be designing a schema to use. I had no idea what that should look like, so I learned React with your old tutorial and within a few hours could iterate on a schema to build UI components like theirs in the browser. This was amazingly helpful to me, and looked way more impressive than it actually was when I showed the boss! I just doubt that I'd do that based on your current tutorial, because I'd be on a Windows machine and get hung up installing NPM or something silly.. and that feels like a shame to me.
Thanks for sharing the concerns. It's a bit of a tough balance. For example before we mentioned the prerequisites like understanding ES5 and basics of ES6, people were complaining that we don't make the assumed knowledge clear. Before we used ES6, people were complaining our code doesn't look like the ones they see in examples and docs for other libraries. Et cetera. Somebody always is upset, although maybe we're just doing a bad job. :-(
We do offer an HTML file to download that you can tinker with, but only on "Installation" page rather than the Tutorial. Maybe we can unify them somehow.
Overall, it's frustrating that people tell us about these issues once a year when we release something, instead of raising an issue and discussing it there. :-) If somebody told us on GitHub this is a problem, we would have fixed it a long time ago.
I agree it's a tough balance, and I definitely wouldn't say you're doing a bad job, I hope I don't come across like I think that you are!
I appreciate that frustration, I didn't raise this as a Github issue because it didn't feel actionable and I don't want to spam all your maintainers with a complaint without having something more concrete to suggest. I'll try to put something together though if that'd be useful :)
Dan, it might be worth throwing in links to CodeSandbox/StackBlitz/WebpackBin somewhere obvious in addition to CodePen, since each of those are online IDEs oriented towards working with React.
I've used React occasionally for a couple of years. I just blasted through the tutorial in 10 minutes to refresh my knowledge and check if any best practices changed in the last year or so. It was perfect for this.
As someone who has been learning React for the last couple of days, I found the tutorial quite adequate. My approach to learning was first going through the tutorial, then I began working on a real project, revisiting the tutorial code every time I needed to refresh my memory about some concept. I do agree it could've been more comprehensive and dealt with some real world scenarios like inputs, data-binding and whatnot, but generally speaking it was a nice showcase of what React can do.
Thanks for replying. With respect to the insight in using React, I assume that the majority of React users are using it to build websites/SPAs, with concerns such as client/server data flows, templating/styling, and URL routing. While the tutorial does demonstrate a good demonstration how React works, it doesn’t provide much practical knowledge for building websites, and worse, doesn’t provide info on how to start building a website. (which just leads me to look at another tutorial)
They tried to add routing to to docs/tutorials. react-router devs hijacked the effort, ground it to a halt with claims of copyright to their code, and the pull request to docs got rejected in the end
I think "requiring you to have a strong JS frontend background in the first place" is NOT a bad thing. People really should be learning the basics before diving into using a framework. Unless, of course, the goal of ReactJS is to give non-JavaScript developers access to application creation. But I suspect not.
Ideally the goal of a tutorial is to give an idea of the basics before diving in, and to properly assess the skill level necessary to take the full dive into a real application.
Good job, fantastic. Don't let the parent complainer get you down, you really nailed it. There's a reason everyone uses React and you're a large part of that reason. Kudos.
It's been a year or two since I did some rails, but what I vaguely remember as uncomfortable was the lack of something like guidance on the "project-level". I could never figure out which components to pick for the stack, or even where to place certain types of files.
I know most of that isn't really react's responsibility. It just happens to inhabit this sort of central position within today's JS that people look at it for guidance.
I'll be stoned here at HN for saying this, but I always considered Rails to be the high-water mark in terms of standardisation: with some experience, you could join any project and were already familiar with the folder structure and many other conventions.
I think there's something like a "React Starter Pack" project now that seems to do exactly what I was looking for last year: a set of known-good components, (pre-)configured, tested, and with the virtual stamp of approval from people who know more than me.
Yeah, the React team has really tried to avoid "blessing" any specific tools or approaches, for several reasons. Facebook uses React in certain ways that are different than the community, and the community is doing a lot of different things anyway.
CRA helps with getting started by providing an opinionated build setup, but leaves the entire rest of the application structure up to you. Sounds like you're looking for something more on top of that.
I think I vaguely tossed out an idea of "CRA templates" on Twitter not too long ago, where maybe in addition to telling CRA what version of `react-scripts` you want to use, you could also give it a template package name. That way, you could specify something like `--template simple-react-redux` or `--template my-react-router-semantic-ui-setup` or something.
There's actually a pretty similar issue with Redux too (and I say that as a Redux maintainer). I opened up an issue a while back to get ideas for what a better starting experience with Redux might look like: https://github.com/reactjs/redux/issues/2295 .
This does bring up an interesting point about the community and its different populations.
JS includes _a lot_ of people, of all levels. You don't really have much choice but to do the lowest common denominators (people newer to it probably consist of the majority right now).
When I went through the VueJS stuff originally, I had a feel of "Come on, get to the point already" as I went through pages over pages to get the whole idea.
When I learnt React (originally when it came out), I looked at the first page, went quickly over the element creation (I was anti-jsx at the time. Times long gone, haha) and lifecycle hooks in like 5 minutes, went "Okay, got it. I already know how this works" and built an app.
Obviously my situation is not the common one, so doc like VueJS should be standard...but having a good "tl;dr" is critical (maybe it is in there, I didn't look, but when I learnt Vue's basic, by the time I went through most of the pages looking for a tl;dr, I had found everything else)
Before even finishing your comment, in my head I was saying "compared to vue.js where the tutorials instantly clicked for me". I'm no master js guru, and agree completely with you.
The most amazing thing, to me, regarding React, is that it's a pretty awesome framework, from the perspective of a developer.
...and yet, I go and try to use Facebook, and the experience is totally fucking repellent.
Even in a closed third-party testing loop, when you control for social variables and human factors, by populating your circle with only fake test accounts you control and have created yourself, for which no one else has the password. (e.g. staging a hypothetical sequence of events, to model an expected experience)
Just trying to do anything is met with the most bizarre and byzantine behaviors and switcheroos.
Opposite experience here. I usually reference FB as an example of a very close to optimal user experience given the magnitude of functionality. Rarely lost, easily discoverable, easy to use.
thaaaaaaaaat's a great point. I use it very often. Daily for probably 4 years? more? It's likely that I am misjudging the usability given that it's basically a small extension of my life.
I'm not trying to be disrespectful, and I fully understand that there's a huge, huge ream of people working to deliver Facebook, but honestly, I could fill multiple volumes of multiple books with the things that Facebook does wrong, and some of it is surely deliberate dark patterns, with specific behavioral objectives, but other aspects are not.
Nevermind whether or not one agrees or disagrees with the all-encompassing nature of Facebook's grip on so many social circles, or whether one has an opinion about Facebook's policies and business practices, the website itself is pretty bad. Bad enough that, had I my druthers, I'd be able to create something that out-competes it, if a creation I put forward could clear the sheer gravitational inertia of the network effect that Facebook enjoys. And I realize that's no small claim, but here I am making it anyway.
It's not your fault, specifically that shit sucks on Facebook all over, and I sincerely doubt you'd have the clout necessary to enact change.
Since it'd be a lot to write up, and this is simply yet another peanut gallery web forum, I'll say this much: as a user, I am clueless about the decision tree I'm offered when I log into Facebook, furthermore, so much of Facebook is mystery meat links and who knows why I see half of any of it. Then as soon as a snippet of user-created content appears, it's buried. Go in to check the settings to see what the hell this system is trying to do for me, and I see trashy icons leading to incomplete features that don't even work as advertised, and I never get what I want, when used as directed. After about 30 some-odd clicks per any given session, and maybe 100 sessions of trying and retrying various combinations from a clean cookie, learned helplessness kicks in, I shut down my computer and find something better to do.
BTW, this cuts across several assets and UI's throughout Facebook's offerings as a whole, for all devices.
Addendum: for an example of how it's done right, look at Slack. Slack has a completely different business model and general objective in serving the user, but divorcing this conversation from that fundamental idea, Slack (without being pretentious) gets it right 85% of the time, in that I'm able to do what I want, and get what I need. Facebook, on the other hand, is stepping in shit 75% of the time, and waxes manipulative when not seeming generally confusing and disorganized.
And to return to the original subject at hand, compare Facebook (right now, today) to React's general website and documentation facelift. The comparison turns out to be surprisingly different in quality. (hint: facebook rates lower)
Yeah, I'm not seeing what's bad about the FB experience. Seems simple enough and intuitive to me. It might be a little bloated with features at the top level, but it's easy enough to ignore those. It's simple to scan the feed, post comments, send private messages....etc.
Firstly, I disagree that the Facebook experience is that bad. The content of my social graph is pretty lame these days, but the website itself is pretty usable, and some features (okay, maybe just Messenger) are top tier.
But secondly and more importantly, it seems bizarre to be amazed that a useful developer tool could be used to make a website that you don’t enjoy. Of course any decent developer tool could be used to make products that you enjoy as well as products you don’t enjoy.
>Just trying to do anything is met with the most bizarre and byzantine behaviors and switcheroos.
Apart from viewing your timeline, posting a status message, commenting on posts, sending messages, and liking things --
all of which seem pretty normal in use -- what else would you do?
Anything else is probably a niche use, and not optimized (or having anyone care about it), including FB apps.
My biggest gripe (aside from the flood of stupid bullshit in my newsfeed which isn't directly Facebook's fault) is that the search bar at the top no longer lets me go straight to people's profiles.
It'll go as far as giving autocompelte suggestions of people's full names, but then you click on the person you want and it gives you search results for them.
I think they did this so that when you search for a name they can show you all the other shit that the person is tagged in, but all I wanted was to get to their wall and post something.
Less charitably, by dumping you to an intermediate page and making you click again for their profile, FB gets to serve another batch of ads. And depending on what metric you measure it "increases engagement!!!" because it took me twice as long to get what I wanted.
This kind of seems like a non-sequitur. A tool is just a tool, it can be used to create both good and bad user experiences. In terms of the technical implementation of a complex website, especially with regard to latency and component rendering correctness/completeness, Facebook has long been the gold standard, even well before React was formalized and released.
As a developer, I fully understand that the nails and girders used to assemble a building aren't expected to reflect the preferences embodied by the final construction they contribute to, but would you just look at the React website, and stand it next to Facebook itself? One looks and feels like shit, and the other does not.
I'm just one guy with an opinion, but I strongly disagree that Facebook is a model example of a complex website. Facebook is blessed with a money hose, that ultimately washes away so many other problems, meanwhile provided that Facebook is not a network hardware and CDN company, I'd contest that if that's what they wind up bragging about, incidentally, then that's clearly a hint that they've gotten their core offerings wrong.
Yes, Facebook started as a PHP garbage pile, and now it's got more going on, but the surface UX of Facebook remains a garbage pile, whether it's a fast garbage pile in terms of line speed, or a photo-realistic representation of a virtual garbage pile.
If I can get consistent browsing results, productive interactions, and notice a presentable style and appearance on a React documentation website, which is a wholly-owned property of Facebook, then why isn't the flagship Facebook system provided to end-users with the same nuanced attention to detail?
It does, you can write this with a Babel preset supporting this feature:
class Foo extends Component {
state = {
foo: '',
};
// The arrow function here is what you're looking for.
onChange = ({ target }) => {
this.setState({
// You can of course use `foo` directly as the key if you just have the one input.
[target.name]: target.value,
});
};
render () {
return <input type="text" name="foo" value={this.state.foo.value} onChange={this.onChange} />;
}
}
This is very timely for me - I was just looking for a new static site generator and so far I've tried out Hugo, Hexo and Jekyll but I didn't like any of them because they're so configuration dependent. I'd rather write my static pages using tools that I already know how to use.
Searching for a static site generator that uses React, I found Phenomic first then Gatsby. I was already leaning towards Gatsby since Phenomic is still in alpha. Now that Facebook is using it, my decision is easy. Phenomic looks like it can do a lot more than Gatsby, so maybe I'll give it a second chance in the future.
Check out Working Copy, which I use extensively but I'm not sure it's what your looking for exactly (I'm not affiliated). I think there's iOctocat if you're just looking for a way to browse github repos.
Both. Checkout gatsbyjs.org, the tool the site was built with. But basically Gatsby renders each page to HTML and writes it out to disk similar to other static site generators. And then when the HTML loads, it pulls in JavaScript to make the site "live" so that from then on out it acts like a normal React web app.
Gatsby is an attempt to blend the best aspects of static site generators and web apps.
No, these are "class fields" rather than arrow functions, and are not part of ES2015. This is why we're not using them in the docs yet. Indeed they would make everything a bit nicer :-)
This web site doesn't follow best practices of not saying what it is, not giving any examples, not letting you see it in action, making users have to read through outdated, long manuals that if you follow directly you get unexplained error messages you have to Google, needing to watch and follow along with a 15 minute youtube video whose first 10 minutes talk about the different choices of IDE's that you have, how to download and save a file from the Internet, and finally whose last 5 minutes do something obscure and contrived, that is the the wrong way to do something.
In fact, if you go to reactjs.org, within the first 7 seconds you can see live examples. (By scrolling down.) If you click the prominent "get started" button prominent at the top of the page, you get taken to a page that says "The easiest way to get started with React is to use this Hello World example code on CodePen" and a single click gets you there. The intro tutorial itself quickly walks you through everything, gearing up from basics to an advanced summary quickly in a well-structured way. It has a "help I'm stuck!" section that tells you exactly what you need to do if you are stuck.
This needs to die.
Someone needs to go about writing some half-assed documentation and putting it up on github without any usable links.
Information is meant to be hidden, and the role of documentation, such as reactjs.org, is properly to hide the nuggets of usable information among false starts, unexplained terminology, long flowing paragraphs of flowery prose that reduce to "", important notes that can only affect people who already know everything else about the thing in question, such as information about upgrades and transitions, and just generally give the sort of impression you get when you read through useless government paperwork.
Take note, people. if you make a site like this, then you can end up being the best-adopted and most popular solution in your entire industry - that's no way to program. Documentation is meant to be a hurdle, a kind of euthanasia program that takes enthusiastic new visitors and tears out their enthusiasm, destroys their will to live, and grinds them down with prose.
Is it possible to use React with a custom canvas-rendered UI? Is it in any way benefitial to do so compared to not using React for the custom canvas-rendered UI?
Text selection is generally a pain in canvas. That's pretty important for docs and examples. HTML is specifically made for displaying text and text is basically all the React site does. No need to fight an uphill battle when you already match the ideal case.
Gatsby generates HTML pages for each page so it loads as fast or faster than other static site generators but is way faster when clicking around the site as it prefetches pages and renders them in the client so the site feels like a local or native app.
It's also fully setup for building with leading modern web development tools like React, webpack, all CSS options including css-in-js, code splitting, PWA techniques, etc. so the development experience is excellent and you get production quality code without any setup.
128 comments
[ 0.27 ms ] story [ 156 ms ] threadWriting static content is basically like building a normal website with a nice templating system. Dynamic content is simply React components that I'm use to working with on complex applications.
Easy to build, easy to deploy, and easy to change.
I had to abandon it for a project that was generating static SEO pages, it was something on the order of 2000 pages and Gatsby couldn't handle it. Hopefully they resolve that soon!
Or, hopefully, they don't. SEO pages suck users time.
I abandoned my own React-based SSG because it was slow, but I'm hoping to dust it off when I have some more time to see the effects.
I haven't used TypeKit in a while, but it looks like they had this issue a year ago [1]. Unclear if it has been fixed or what. A lot of people I know simply embed the font in the page (ugh)
[1] https://blog.typekit.com/2016/06/03/regarding-the-flash-of-u...
Contrast with the official Vue.js tutorial (https://vuejs.org/v2/guide/), which goes through things step by step with normal HTML syntax.
> We hope the new site will make it easier for you all to contribute improvements as well. We look forward to working with you to improve it! [1]
This was just the first phase of them moving to the new site. They understand that the docs can be better. Maybe instead of just complaining about them, you contribute to them to make them more "noob" friendly, like you are describing.
[1] https://twitter.com/reactjs/status/913797589421629440
Is that a high bar for a JS frontend framework? Serious question, as it doesn't seem that way to me. This seems analogous to saying "Django docs require you to know python" or "Postgres docs require you to understand how databases work".
It is easily the most rage-inducing programmer moment I ever had, mainly because it's so fucking stupid and the only reason it took me so long was because the actual tutorial and documentation was fucking lying to me.
Technically speaking they fixed it by now: they mention the bind-thingy under "Handling Events" in the documentation, which you randomly have to stumble upon:
However, the tutorial is still deceiving: This is fine in this specific situation because the render method uses a closure: But this is a subtle nuance that can be an incredible pain to figure out. There is no mention of all the this-related pains in the tutorial anywhere.[0] https://reactjs.org/tutorial/tutorial.html
[1] https://reactjs.org/docs/handling-events.html
React documentation switched from `React.createClass` to ES6 classes because they community already did at that point, and wanted to see the more "mainstream" pattern documented. I'm sorry it wasn't obvious that there is a difference between the function call and the language syntax, but it's definitely not a change in React.
The tutorial you mention works fine because `onClick={() => this.handleClick(i)}` is an alternative way to bind methods that also works. That's what the tutorial uses because it's easier to explain React first without diving into how `this` works in ES6 classes. And you can run that code and verify it works. (Every step of the tutorial has a link with a code example.) So no, it has not been broken for a year.
We also did blog about ES6 class support: https://reactjs.org/blog/2015/01/27/react-v0.13.0-beta-1.htm...
And autobinding of `React.createClass` (which you can still use—it's just in a separate package) is also still documented: https://reactjs.org/docs/react-without-es6.html
That said I'm sorry about your bad experience.
> We also did blog about ES6 class support
Not everyone reads blogs all the time. If a new product is released, it's reasonable to expect the documentation to mention the breaking changes.
React.createClass() always did (and still does) autobinding.
ES6 classes never supported autobinding.
We couldn't have changed your code from one to the other. There is no "release notes" associated with that change—changing the syntax was a conscious decision you made either when converting or when writing a new components.
It can be nearly impossible to Google something if you don't even know what it is that you don't know.
There's a comment by, well, YOU, from March this year[0] on a github issue discussing improvements to documentation, suggesting it is one of the most common troubleshooting issues, so I'm not the only idiot failing to grasp this when first diving into webdev.
It would help tremendously if there was even just a simple sentence in the tutorial like:
> "By the way, we are using an arrow function here because JavaScript has some subtle behaviour when it comes to this, but explaining the details of that here would take too long. See [here], [here] and [here]"
.. with a few links explaining both this and ES6 classes in more detail. Because otherwise you can easily get stuck not even knowing where to look for the cause of the bug.
[0] https://github.com/facebook/react/issues/8060#issuecomment-2...
That you've written so much indicates to me that you expect other people (like a framework's documentation) to introduce you to every language idiosyncrasy in any place you happen to be reading.
That's not what I want people to expect from me as a professional. People should be able to expect me to credentialize in the domain at hand.
onClick = {this.handleClick}
This is due to the way "this" is scoped in JS.
Dan mentions that it works fine if you instead do: onClick = {() => this.handleClick()}
This is using the new ES6 arrow functions which fix the "this" scoping problem.
Another alternative is to use bind() inside the onClick and set "this" to the correct value that you want.
onClick = {this.handleClick.bind(this)}
It's true that we assume preexisting JS knowledge, but your other point about how it doesn't give much insight into using React is one I haven't heard before. Can you say more about what you mean?
Anecdotally in my experience, most people seem to find the tutorial pretty helpful, but we can think about more options. Maybe there's space to add one that assumes less about JS. (And really -- thank you for complaining about this, or else we wouldn't have known.)
I feel like React expects me to have a deep knowledge of JS build tooling when all I care about getting started is building a page locally that works and does cool things.
FWIW this is how Vue's tutorial starts - and another really nice thing they do is teach you the API by entering things into your console on their tutorial page full of components.
I don't really know if this is constructive or useful, I hope it is - I just feel like React expects a lot of new users in a way it didn't used to.
https://reactjs.org/tutorial/tutorial.html#how-to-follow-alo...
Similarly, the installation page offers you to either download a single HTML file, or to install a CLI that gives you a project that's ready to go: https://reactjs.org/docs/installation.html
Could you clarify what give you an impression that you need to have a deep knowledge of build tooling to follow along?
I'll try to clarify. If you don't mind another comparison to Vue, their equivalent page: https://vuejs.org/v2/guide/ says "Or, you can create an index.html file and include Vue with: <script src="https://unpkg.com/vue"></script>", while your get started page says "If you’d rather use a local development environment, check out the Installation page." I know, if I click there it'll say I have an index.html and I know I shouldn't do it that way, but if I have none of the infrastructure on my computer and I want to build my thing on my computer, I'm looking for the script - not installation instructions.
On that 'how to follow along' page, under prerequisites it says "Note that we’re also using some features from ES6, a recent version of JavaScript. In this tutorial, we’re using arrow functions, classes, let, and const statements. You can use Babel REPL to check what ES6 code compiles to.". If this was the first React tutorial I ever looked at I'd be completely lost here and concluding I don't understand the prerequisites. If I know anything about 'relatively new' things in Javascript or Babel then I assume that I'm expected to use it somehow to actually use those relatively new things in my browser, but I have no idea how.
Also, scrolling down a bit, "if you prefer to write code in your editor" is a list of 6 steps, one of which is installing Node and another is "Follow the installation instructions to create a new project." I might not need deep knowledge, but this feels like a lot of stuff to do to follow a tutorial in my editor.
Here's my story about the old, do-it-all-locally tutorial: I'd just started an internship, and got a brief about doing some dynamic UI generation from schemas in .net stuff I'd never used, and was meant to be designing a schema to use. I had no idea what that should look like, so I learned React with your old tutorial and within a few hours could iterate on a schema to build UI components like theirs in the browser. This was amazingly helpful to me, and looked way more impressive than it actually was when I showed the boss! I just doubt that I'd do that based on your current tutorial, because I'd be on a Windows machine and get hung up installing NPM or something silly.. and that feels like a shame to me.
We do offer an HTML file to download that you can tinker with, but only on "Installation" page rather than the Tutorial. Maybe we can unify them somehow.
Overall, it's frustrating that people tell us about these issues once a year when we release something, instead of raising an issue and discussing it there. :-) If somebody told us on GitHub this is a problem, we would have fixed it a long time ago.
I appreciate that frustration, I didn't raise this as a Github issue because it didn't feel actionable and I don't want to spam all your maintainers with a complaint without having something more concrete to suggest. I'll try to put something together though if that'd be useful :)
I agree though that there is a niche for the other kind of tutorial you're describing. :-)
That shouldn't be its purpose.
Full pull request is here: https://github.com/facebook/react/pull/8848
As a result one of the React contributors ended up apologizing to react-router https://github.com/facebook/react/pull/8848#issuecomment-285...
EDIT: missing the "NOT" in my opening sentence.
https://news.ycombinator.com/item?id=15367480
(I think people didn't get it.)
Good job, fantastic. Don't let the parent complainer get you down, you really nailed it. There's a reason everyone uses React and you're a large part of that reason. Kudos.
I know most of that isn't really react's responsibility. It just happens to inhabit this sort of central position within today's JS that people look at it for guidance.
I'll be stoned here at HN for saying this, but I always considered Rails to be the high-water mark in terms of standardisation: with some experience, you could join any project and were already familiar with the folder structure and many other conventions.
I think there's something like a "React Starter Pack" project now that seems to do exactly what I was looking for last year: a set of known-good components, (pre-)configured, tested, and with the virtual stamp of approval from people who know more than me.
CRA helps with getting started by providing an opinionated build setup, but leaves the entire rest of the application structure up to you. Sounds like you're looking for something more on top of that.
I think I vaguely tossed out an idea of "CRA templates" on Twitter not too long ago, where maybe in addition to telling CRA what version of `react-scripts` you want to use, you could also give it a template package name. That way, you could specify something like `--template simple-react-redux` or `--template my-react-router-semantic-ui-setup` or something.
There's actually a pretty similar issue with Redux too (and I say that as a Redux maintainer). I opened up an issue a while back to get ideas for what a better starting experience with Redux might look like: https://github.com/reactjs/redux/issues/2295 .
JS includes _a lot_ of people, of all levels. You don't really have much choice but to do the lowest common denominators (people newer to it probably consist of the majority right now).
When I went through the VueJS stuff originally, I had a feel of "Come on, get to the point already" as I went through pages over pages to get the whole idea.
When I learnt React (originally when it came out), I looked at the first page, went quickly over the element creation (I was anti-jsx at the time. Times long gone, haha) and lifecycle hooks in like 5 minutes, went "Okay, got it. I already know how this works" and built an app.
Obviously my situation is not the common one, so doc like VueJS should be standard...but having a good "tl;dr" is critical (maybe it is in there, I didn't look, but when I learnt Vue's basic, by the time I went through most of the pages looking for a tl;dr, I had found everything else)
React feels so much nicer and it's use of Vanilla JS makes it so much easier to debug. It's a breath of fresh air.
...and yet, I go and try to use Facebook, and the experience is totally fucking repellent.
Even in a closed third-party testing loop, when you control for social variables and human factors, by populating your circle with only fake test accounts you control and have created yourself, for which no one else has the password. (e.g. staging a hypothetical sequence of events, to model an expected experience)
Just trying to do anything is met with the most bizarre and byzantine behaviors and switcheroos.
Nevermind whether or not one agrees or disagrees with the all-encompassing nature of Facebook's grip on so many social circles, or whether one has an opinion about Facebook's policies and business practices, the website itself is pretty bad. Bad enough that, had I my druthers, I'd be able to create something that out-competes it, if a creation I put forward could clear the sheer gravitational inertia of the network effect that Facebook enjoys. And I realize that's no small claim, but here I am making it anyway.
It's not your fault, specifically that shit sucks on Facebook all over, and I sincerely doubt you'd have the clout necessary to enact change.
Since it'd be a lot to write up, and this is simply yet another peanut gallery web forum, I'll say this much: as a user, I am clueless about the decision tree I'm offered when I log into Facebook, furthermore, so much of Facebook is mystery meat links and who knows why I see half of any of it. Then as soon as a snippet of user-created content appears, it's buried. Go in to check the settings to see what the hell this system is trying to do for me, and I see trashy icons leading to incomplete features that don't even work as advertised, and I never get what I want, when used as directed. After about 30 some-odd clicks per any given session, and maybe 100 sessions of trying and retrying various combinations from a clean cookie, learned helplessness kicks in, I shut down my computer and find something better to do.
BTW, this cuts across several assets and UI's throughout Facebook's offerings as a whole, for all devices.
And to return to the original subject at hand, compare Facebook (right now, today) to React's general website and documentation facelift. The comparison turns out to be surprisingly different in quality. (hint: facebook rates lower)
But secondly and more importantly, it seems bizarre to be amazed that a useful developer tool could be used to make a website that you don’t enjoy. Of course any decent developer tool could be used to make products that you enjoy as well as products you don’t enjoy.
Apart from viewing your timeline, posting a status message, commenting on posts, sending messages, and liking things -- all of which seem pretty normal in use -- what else would you do?
Anything else is probably a niche use, and not optimized (or having anyone care about it), including FB apps.
It'll go as far as giving autocompelte suggestions of people's full names, but then you click on the person you want and it gives you search results for them.
I think they did this so that when you search for a name they can show you all the other shit that the person is tagged in, but all I wanted was to get to their wall and post something.
Less charitably, by dumping you to an intermediate page and making you click again for their profile, FB gets to serve another batch of ads. And depending on what metric you measure it "increases engagement!!!" because it took me twice as long to get what I wanted.
I'm just one guy with an opinion, but I strongly disagree that Facebook is a model example of a complex website. Facebook is blessed with a money hose, that ultimately washes away so many other problems, meanwhile provided that Facebook is not a network hardware and CDN company, I'd contest that if that's what they wind up bragging about, incidentally, then that's clearly a hint that they've gotten their core offerings wrong.
Yes, Facebook started as a PHP garbage pile, and now it's got more going on, but the surface UX of Facebook remains a garbage pile, whether it's a fast garbage pile in terms of line speed, or a photo-realistic representation of a virtual garbage pile.
If I can get consistent browsing results, productive interactions, and notice a presentable style and appearance on a React documentation website, which is a wholly-owned property of Facebook, then why isn't the flagship Facebook system provided to end-users with the same nuanced attention to detail?
https://github.com/tc39/proposal-class-fields
Changes to the language take time, but then they benefit everyone and not just a particular library.
--- quote ---
With the ESnext field declarations proposal, the above example can be written as
--- end quote ---this.onclick = this.clicked.bind(this); etc. are all still there
Also, your example is not equivalent to either the complaint in the original comment or to the code snippet I quoted
Also: React has been binding event handlers to `this` since forever without presets (update: only in React.creatClass though)
Yes, with public fields you can write
and it works like if you bound it in the constructor.Hope this helps.
Searching for a static site generator that uses React, I found Phenomic first then Gatsby. I was already leaning towards Gatsby since Phenomic is still in alpha. Now that Facebook is using it, my decision is easy. Phenomic looks like it can do a lot more than Gatsby, so maybe I'll give it a second chance in the future.
Also this is the source for the website: https://github.com/facebook/react/blob/master/www/package.js...
Does this mean the HTML is constructed by rendering components to strings using ReactDOMServer, or that the frontend scripts use React? Or both?
Gatsby is an attempt to blend the best aspects of static site generators and web apps.
In fact, if you go to reactjs.org, within the first 7 seconds you can see live examples. (By scrolling down.) If you click the prominent "get started" button prominent at the top of the page, you get taken to a page that says "The easiest way to get started with React is to use this Hello World example code on CodePen" and a single click gets you there. The intro tutorial itself quickly walks you through everything, gearing up from basics to an advanced summary quickly in a well-structured way. It has a "help I'm stuck!" section that tells you exactly what you need to do if you are stuck.
This needs to die.
Someone needs to go about writing some half-assed documentation and putting it up on github without any usable links.
Information is meant to be hidden, and the role of documentation, such as reactjs.org, is properly to hide the nuggets of usable information among false starts, unexplained terminology, long flowing paragraphs of flowery prose that reduce to "", important notes that can only affect people who already know everything else about the thing in question, such as information about upgrades and transitions, and just generally give the sort of impression you get when you read through useless government paperwork.
Take note, people. if you make a site like this, then you can end up being the best-adopted and most popular solution in your entire industry - that's no way to program. Documentation is meant to be a hurdle, a kind of euthanasia program that takes enthusiastic new visitors and tears out their enthusiasm, destroys their will to live, and grinds them down with prose.
https://en.wikipedia.org/wiki/Poe%27s_law
Gatsby generates HTML pages for each page so it loads as fast or faster than other static site generators but is way faster when clicking around the site as it prefetches pages and renders them in the client so the site feels like a local or native app.
It's also fully setup for building with leading modern web development tools like React, webpack, all CSS options including css-in-js, code splitting, PWA techniques, etc. so the development experience is excellent and you get production quality code without any setup.
Gatsby's ambitions are much higher than simply transforming markdown into HTML. See the writeup of the talk I gave recently describing Gatsby as a website compiler https://www.gatsbyjs.org/blog/2017-09-13-why-is-gatsby-so-fa...