document happy path(s) for adding Paragon to new create-react-app projects

[brian-smith-tcril]

@cintnguyen brought this to my attention after hitting a few snags when learning how to consume Paragon components. It seems if someone trying to add Paragon to a new create-react-app project follows the instructions in the getting started part of the readme, they will likely encounter some errors.

It would be great to add some clarification around dependencies to the docs/readme so new consumers of Paragon can get up and running without issues.

repo steps

• create react app using npx create-react-app my-app
• downgrade to react 16
  • delete package-lock.json and node_modules
  • replace react and react-dom version ^18.2.0 in package.json with ^16.14.0 (version in frontend-template-application)
  • replace @testing-library/react version ^13.4.0 with ^12.1.5
  • in index.js replace import ReactDOM from 'react-dom/client'; with import ReactDOM from 'react-dom';
  • in index.js replace

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

with

ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('root')
);

🎉 everything runs with npm start

• install paragon npm i --save @edx/paragon
• add a component to App.js, for example: a button
  • import { Button } from '@edx/paragon';
  • <Button variant="primary" className="mb-2 mb-sm-0">Primary</Button>

❌ get Cannot find module 'sass' error

• install node-sass via npm install --save-dev sass
• rename index.css to index.scss
• add @import '~@edx/paragon/scss/core/core.scss'; to the top of index.scss
• replace import './index.css'; in index.js with import './index.scss';

❌ get Cannot find module '@edx/browserslist-config' error

• install @edx/browserslist-config via npm install --save-dev @edx/browserslist-config

🎉 it works

[brian-smith-tcril]

another create-react-app happy(ish) path:

nvm use 18
npx create-react-app my-app
cd my-app/
npm i --save-dev sass
npm i --save @edx/paragon --legacy-peer-deps
npm i --save-dev @edx/browserslist-config --legacy-peer-deps

replace App.js with

import { Alert } from '@edx/paragon';
import './App.css';

function App() {
  return (
    <div className="App">
        <Alert variant="success">
          Paragon component added to Create React App page successfully!
        </Alert>
    </div>
  );
}

export default App;

• rename index.css to index.scss
• add @import '~@edx/paragon/scss/core/core.scss'; to the top of index.scss
• replace import './index.css'; in index.js with import './index.scss';

see

why this is happy(ish) instead of just happy

• extensive use of --legacy-peer-deps
• warning from webpack

One of your dependencies, babel-preset-react-app, is importing the
"@babel/plugin-proposal-private-property-in-object" package without
declaring it in its dependencies. This is currently working because
"@babel/plugin-proposal-private-property-in-object" is already in your
node_modules folder for unrelated reasons, but it may break at any time.

babel-preset-react-app is part of the create-react-app project, which
is not maintianed anymore. It is thus unlikely that this bug will
ever be fixed. Add "@babel/plugin-proposal-private-property-in-object" to
your devDependencies to work around this error. This will make this message
go away.