Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/clearmatics/qreacto

Run standalone React components in your Quarto project!
https://github.com/clearmatics/qreacto

Last synced: 14 days ago
JSON representation

Run standalone React components in your Quarto project!

Awesome Lists containing this project

README 

        
# React components in Quarto



Run standalone React components in your Quarto project!



Check out the [demo](https://clearmatics.github.io/qreacto/example.html)!



## Installation



To install this extension in your current directory (or into the Quarto project that you're currently working in), use the following command:



``` bash

quarto add clearmatics/qreacto

```



## Running a React component



To run a React component, first, create a folder called `_components/` in the root of the project.

Then in that folder, create your component in a .jsx or .tsx file. For example:



``` javascript

/**

 * An example of React with fetch

 * @returns 

 */

function FetchComponent() {

    // ...

}



```



Next, add the shortcode into the .qmd file where you want the component to be displayed:



``` bash

{{< react FetchComponent >}}

```



If you are using TypeScript, the extension will automatically detect the file type and use the correct Babel preset. 



However, you can also be explicit:



``` bash

{{< react FetchComponent type="typescript" >}}

```



Ensure that the name of the component and the name of the file match for the filter to work correctly. **It is also case sensitive.**



For example, if the component is named `FetchComponent`, save it in the file `_components/FetchComponent.jsx` for JavaScript or `_components/FetchComponent.tsx` for TypeScript.



## Adding thirdparty imports



You can leverage ES modules and Content Delivery Networks (CDNs) to import third-party packages directly into your react component, without the need for local installations or bundling. CDNs offer several benefits for importing dependencies.



``` javascript

import * as math from 'https://esm.run/math';



function MyComponent() {

    // ... 

}



```



Make sure the third-party package is available as an ES6 module, either from jsdelivr or esm.run (or any other ES6 module CDN). Import and use the package accordingly.



## Adding local imports



You can also import components from the same folder:



``` javascript

import ButtonExample from "./ButtonExample";



function FetchComponent() {

    // ... 

}

```



## Configuring



In your `_quarto.yml` file, you can configure react to look in a different folder for components and resources:



``` yaml

    react:

        components: _components

        resources: _components

```



Currently, components can only be imported from the same folder. If you have a component in a subfolder, you will need to move it to the same folder as the component you are importing it into.



**Note:** The files should use the same extension as the component you are importing into. For instance, if you are importing into a `.tsx` file, the files you are importing should also be `.tsx` files.



## Supporting files and scripts



JavaScript and CSS files are automatically included in the page. If your component requires a CSS file, include it in the same folder as the component, and it will be included in the page.



Supported files are currently pulled from the `_components` folder (or the folder you specified in your _quarto.yml file). The accepted extensions include `.css`, `.js`, and `.ts`.



## Gotchas



- Avoid including imports of React in your component, as Babel will already provide this on the window.

- Importing and using some ESM React components can cause the compiler to fail. This can be a bit hit and miss. Some components like [react-google-recaptcha](https://www.npmjs.com/package/react-google-recaptcha) worked fine, but others had compilation issues. Remember, this extension is designed to build small lightweight components to compliment your Quarto project. If you're pulling in lots of outside React components, consider creating a react app instead.



## Known issues and tasks still to do

- [ ] Arrow functions are not currently supported. The Babel plugin `transform-arrow-functions` conflicts with the Babel TypeScript preset. This is currently being investigated.

- [ ] Allow deep imports

- [x] infer the file type (and then set the preset) during the lua filter rather than having to specify it in the shortcode (eg don't need to specify `type="typescript"` in the shortcode)

- [ ] Named imports are not currently supported `import { NamedButton } from './Button';` will not work but `import Button from './Button'` will.

- [ ] Typescript types and type casting not working as expected. for example `as unknown as MyType` will throw



## Getting started with development



If you would like to contribute, there's a [readme](https://github.com/clearmatics/qreacto/blob/main/_extensions/qreacto/README.md) in the `_extension/qreacto` folder that explains the codeflow for the qreacto.lua script, its a great place to start.



To develop the extension, you need to run it in a Quarto project. The quickest way to set up a project is by running the following command in the root directory:



``` bash

quarto create project

```



This command will set up a project that allows you to test the functionality.



React components are to be located in the components/ folder at the root of the project. Some basic examples are already provided.



The script `qreacto.lua` is the main script that is run when the shortcode is encountered. It is located in the `_extension/qreacto` folder.



## Contributing

We welcome contributions from the community to help improve and enhance this project. Whether you want to report a bug, suggest a new feature, or submit code changes, your efforts are highly appreciated.



## Reporting Issues

If you encounter any bugs, glitches, or unexpected behaviour while using this project, please open an issue on the GitHub repository. When reporting issues, please provide as much information as possible, including the steps to reproduce the problem and details about your environment.



## Suggesting Enhancements

If you have ideas for new features or improvements, feel free to create an enhancement request in the GitHub repository. We value creative ideas that can add value to the project and its users.



## Code Contributions

We encourage contributions from developers of all skill levels. If you want to contribute code changes, please follow our [Contributing](CONTRIBUTING.md) guidelines.



## Code of Conduct

Please note that we adhere to a Code of Conduct in this project. All contributors are expected to follow these guidelines to ensure a friendly, inclusive, and respectful environment for everyone.



By contributing to this project, you agree to abide by the Code of Conduct, which can be found in the repository's [Code of Conduct](CODE_OF_CONDUCT.md) file.



## Getting Help

If you need help or have questions about contributing, feel free to reach out to us by creating an issue or joining our community channels. We are more than happy to assist you throughout the process.



Thank you for your interest in contributing to this project! Your contributions play a vital role in making this project better for the community. We look forward to your involvement and collaboration. Happy contributing!