[Doc] Tutorial: Fix typos, snippets and file extensions

[erikvanderwerf]

Fix #8606

1. Moved the diff marker to the "posts" line, as expected.
2. Minor spell-checks.
3. Updated sample TypeScript in Tutorial to compile with typescript@4.9.4

[djhi]

Thanks!

[erikvanderwerf]

^ Sorry! I tried to hit the buttons for both but GitHub is being weird.

[djhi]

I'm sorry I should have say so in your initial issue :(

[fzaninotto]

I'm sorry if I wan't clear. I meant the code should be pure JS, but the files should be .ts and .tsx. When the TS compilation fails with pure JS code, we can add a note after the JS snippet to explain how to modify the file for make it work.

[erikvanderwerf]

I don't feel comfortable doing that. If the examples are JavaScript then own it. What's the value in the TypeScript extension if you are not actually using it? JavaScript code belongs in .js files, with notes on how to make it work in .ts.

[erikvanderwerf]

The tutorial directory (https://github.com/marmelab/react-admin/tree/master/examples/tutorial/src) is written with .ts files, so anyone reading both the code and the instructions will notice the difference.

[slax57]

Also, as asked by @fzaninotto , you should leave all the file extensions as *.ts or *.tsx.

Indeed the tutorial is written so that typescript is enabled, and also the file paths will match the files from the sample repository.

If ever a code snippet, written in pure JS but saved in a TS(X) file raises a warning in your IDE, we simply need to mention it beneath or inside the snippet as comment, just like you did.

[erikvanderwerf]

I did not change any file extensions in the repo. If you are referring to the snippets' // in ... comments, it would be misleading to someone making their own project to leave them as TS.

Walk through the tutorial yourself as a new user, like I did. It is confusing to make TypeScript files that do not compile. I would rather understand that the example is written in JS, and any upgrades to TS are on my own. I would understand that more is required from me.

[erikvanderwerf]

If the examples are written in TS, why not update the tutorial to reflect that? It would be clearer for everyone.

[slax57]

@erikvanderwerf Yes I am referring to the snippets' // in ... comments

I know it's a bit confusing, because we are currently between two seats. But I'll try my best to explain.

• We cannot (for now) change the snippets to TS, for technical reasons (they are not yet supported by our code highlighter) and also because we do not want to turn off people who are still not ready to use TS and only know JS
• We name our files *.ts and *.tsx because, on the other hand, we want to encourage the reader to use TS (since it's a good opportunity because they are starting a new project) and also because they match the file names from the tutorial example in the repo
• So we end up in this compromise of a solution that consists in having JS code inside .ts files. But as you saw, only a handful of files require adjustments to get rid of the TS warnings. Most of the snippets can be copy-pasted with no issues at all. That's why we consider it to be a good compromise for now.

Hopefully this will make it clearer for you why we ask for these changes.

[erikvanderwerf]

Technological challenges are a valid reason for not upgrading the Tutorial code blocks 😄

So if I understand correctly:

1. The code block needs to indicate JS for syntax highlighting purposes (```js).
2. But the comment // in *.ts will indicate TS to encourage people to use TS.
3. But the code as written will be JS, meaning that TS might not compile if a new user copies the code.
4. But with comments in the JS explaining the changes needed so that it would compile in TS.

It certainly is confusing (and I don't exactly agree, but I can live with it). If the above understanding is correct, I'll make the appropriate changes.

[slax57]

@erikvanderwerf Yes that's correct!
Thanks 🙂

[slax57]

Thanks!