oslabs-beta / sapling

Sapling

A convenient way to traverse your React application.
Explore the docs »

Report Bug · Request Feature

About The Project

Sapling is a VS Code extension built with React developers in mind. As your codebase grows, your native file structure becomes less and less intuitive. Wouldn't it be nice to have a file structure that represents the actual relationships between the components and containers in your application? Wouldn't you like a quick reference to your available props, and an indication of routes and conditional rendering?

With Sapling, you don't have to guess at the parent component of your current file. Sapling is an interactive hierarchical dependency tree that lives directly within your VS Code IDE, as accessible as the native file system. You can build your tree by selecting any component file as the root and get information about the available props at any level. It also provides visual indication of Javascript syntax or import errors in your files, and shows you which components are connected to your Redux store.

Built With

• React
• VSCode Extension API
• Mocha
• Chai
• Babel Parser
• Webpack
• GitHub Actions

Installation

Installing from VS Code Extension Marketplace:

1. If needed, install Visual Studio Code for Windows (7+), macOS (Sierra+), or Linux (details).

2. Install the Sapling extension for Visual Studio Code. Search for 'sapling' in the VS Code extensions tab, or click here.

3. Once complete, you'll see Sapling appear in your sidebar. You can now begin using Sapling! Check out the Getting Started below for information on how to get started.

To install sapling for development, please see the contributing section below.

Getting Started

1. After installing VSCode Extension, you will see the extension on your sidebar. Click the "Choose a File" button.

2. Your file explorer window will launch. Select an entrypoint, a file where the parent component for the rest of your application is rendered.

3. Your sidebar will now display a component tree.

Usage

After installing, click the Sapling tree icon in your extension sidebar (image of icon here). From there, you can either click "Choose a file" to select your root component, or build your tree directly from a file open in your editor with the "Build Tree" button on the right hand side of your status bar. Click the + and - buttons to expand and collapse subsets of your tree, and hover over the information icon (image of icon here) to get a list of props available to that component. You can also press the view file icon (image of icon here) to open the file where the component is defined in your editor window. Below is a quick-reference legend for icon and text format meanings. If you prefer not to view React Router or other third-party components imported to your app, you can disable either of these in the VS Code Extension Settings.

Icon Legend in Sapling Tree View:

• available props (hover)
• open file (click)
• Redux store connection
• Navbar: error in file (matches the error color of your theme)
• Navbar: currently open file

Sapling can currently display React apps made with TSX/JSX and ES6 import syntax.

Sapling will detect React components invoked using JSX tag syntax and React-Router component syntax, where React is imported in a file:

    // Navbar will be detected as a child of the current file
    <Navbar />

    // As above
    <Navbar></Navbar>

    // Route and Navbar will be detected as child components of the current file
    <Route component={Navbar} />

    // Route and App will be detected as child components of the current file
    <Route children={App} />

Sapling will detect the names of inline props for JSX components it identifies:

    // props 'userId' and 'userName' will be listed for Navbar in Sapling
    <Navbar userId={...} userName={...} />

Sapling can identify components connected to the Redux store, when 'connect' is imported from 'react-redux', and the component is the export default of the file:

    // App.jsx
    import React from 'react';
    import { connect } from 'react-redux';

    const mapStateToProps = ...
    const mapDispatchToProps = ...

    const App = (props) => {
      return <h1>This is the App</h1>
    }

    // Sapling will detect App as connected to the Redux store
    export default connect(mapStateToProps, mapDispatchToProps)(App);

Note

Sapling prioritizes file dependencies over component dependencies. Consider the following JSX contained in the file App.jsx:

    //App.jsx
    import React from 'react';
    import Home from './Home';
    import Navbar from './Navbar';

    class App extends Component {

      render (
        return {
          <Home>
            <Navbar />
          </Home>
        })
    }

Sapling will display Home and Navbar as siblings, both children of App:

Contributor Usage

1. Download/clone the project from Github
2. Open the 'sapling' folder in your VS Code IDE. The outer 'sapling' folder must be the root folder in the workspace.
3. Open sapling/src/extension.ts
4. To view the webview, in your terminal navigate into the inner 'sapling' folder and run the following command: npm run watch
5. Press F5. A new VSCode window will open with the Sapling Extension.
6. Click the Sapling icon on the left to see the Sapling sidebar.

Note: Ctrl+R (or Cmd+R on Mac) will refresh the extension development host

Extension Settings

This extension contributes the following settings:

• sapling.view.reactRouter: enable/disable React Router component nodes
• sapling.view.thirdParty: enable/disable all third party component nodes

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Creators

• Charles Gutwirth
• Jordan Hisel
• Lindsay Baird
• Paul Coster

Contact

Twitter: @TeamSapling | Email: [email protected]

GitHub: https://github.com/oslabs-beta/sapling/

Acknowledgements

• Parsing Strategy inspired by React Component Hierarchy
• Interactive tree view styling adapted from Pure CSS Tree Menu
• Icons from Font Awesome
• Tooltips with Tippy
• Best README Template
• Sapling Logo from Freepik
• Readme badges from shields.io