Skip to content

docs: fix runnable recipes and tutorial examples - #266

Open
dajiaohuang wants to merge 3 commits into
dai-shi:mainfrom
dajiaohuang:docs/repair-runnable-examples-20261015
Open

dajiaohuang wants to merge 3 commits into
dai-shi:mainfrom
dajiaohuang:docs/repair-runnable-examples-20261015

Conversation

@dajiaohuang

Copy link
Copy Markdown

Summary

Fix copy/paste failures in the existing examples and documentation without changing the library API:

  • Point the README example command and first two playground links at 01_counter and 02_person, which exist in the current examples directory.
  • Close the createContainer calls in the two useState recipes.
  • Remove the person tutorial's import of useDispatch, which its store does not export, and match its flasher ref to the rendered div.
  • Use Immer's named produce export in the recipe and Immer tutorial, compatible with the Immer 10 dependency used by this repository.

Reproduction and validation

Local fixtures were extracted from the documented snippets (not added to the repository):

  • Before the changes, the two recipes fail parsing, the person tutorial fails TypeScript compilation (missing export and incompatible ref), and the Immer tutorial's edit action throws TypeError: ...default is not a function, leaving the displayed todo unchanged.
  • After the changes, the snippets compile, and React DOM fixtures can edit the person name, switch the displayed name, and update the Immer-backed todo.
  • React 19.0.0 / happy-dom: the existing spec plus eight bounded local public-API/documentation checks pass, including normal/concurrent containers, selectors, memoized nested readers, an external-store selector integration, and the existing async example with a deterministic mock API.
  • React 18.3.1: an isolated installation of the packed package passes container, selector, external-store and documented Immer DOM-update checks; installed ESM and CJS exports resolve.
  • ESLint, library/example TypeScript checks, ESM/CJS compilation, and the Docusaurus production build pass.
  • Prettier passes for the staged LF document contents and the checkout with native line-ending handling; git diff --check passes.

The browser/Puppeteer example suite was not run. These are isolated DOM checks, not browser visual or all-version compatibility certification.

@dai-shi dai-shi left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catch. Thanks for the suggestions.

Comment thread website/docs/recipes.md Outdated
Comment on lines +95 to +92
const App = () => (
<Provider>
...
</Provider>
);
const App = () => <Provider>...</Provider>;

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we keep the multiline style?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Restored the original multiline style in both affected Provider examples in a6f388f, keeping the syntax and import fixes unchanged. This follow-up only changes documentation formatting; checked the exact diff and whitespace, without rerunning the earlier React/site tests.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you check CI error? it's probably complaining because the syntax is correct now. ... might need to be {/* ... */} or something.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked the failing job (run 38861492502, job 117242550207). The failure is not a JSX syntax error: pnpm test runs test:format, test:lint, test:types and test:spec together, and it stopped at test:format, which reported a Prettier code-style issue on website/docs/recipes.md and exited 1. The spec suite never started, so the ... lines were not the reported error, and no library code is involved.

The format step fails because Prettier reflows the two multiline Provider/App examples back onto a single line, i.e. it would undo the layout you asked to keep in #266 (comment). The minimal fix is to keep the multiline layout and mark those two declarations, so the pushed commit 2b9f2db only adds // prettier-ignore above each const App = ... in that file — two added comment lines, no other change.

Verified locally against this PR head: using the repo's own pinned Prettier 3.4.2 from pnpm-lock.yaml with the package.json prettier config, prettier --check website/docs/recipes.md fails on the previous head (a6f388f) and passes on 2b9f2db. I did not re-run the rest of the suite or trigger a new workflow run, so the other steps are still unverified by me.

Mark the two Provider/App examples restored for review so prettier
leaves their multiline layout intact, fixing the test:format failure.
Comment thread website/docs/recipes.md

} = createContainer(({ initialState }) => useState(initialState));

// prettier-ignore

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about this?

const App = ({ initialState }) => (
  <Provider initialState={initialState}>
    {/* ... */}
    {/* ... */}
    {/* ... */}
  </Provider>
);

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants