🚀Quick-start Guide

Get familiar with Scandi in a few minutes!

☑️ Prerequisites

Make sure you have installed Node v14. We recommend n (macOS, Linux) or nvm-windows to easily manage different Node installations. Also, npm should be v6.

Also install the ScandiPWA CLI – it's a command-line tool that will help you work with Scandi much faster:

npm i -g scandipwa-cli

📦 Installation

Let's create a new app so we have something to work with! In the terminal, type:

npm init scandipwa-app my-first-app

This will install all required dependencies, and initialize a new Scandi app in my-first-app. Once that has completed, you can take a look at the resulting files:

my-first-app/
├── composer.json
├── i18n/
├── yarn.lock
├── magento/
│   ├── etc/
│   ├── registration.php
│   └── theme.xml
├── node_modules/        # Dependencies live here
├── package.json         
├── public/
├── README.md
└── src/                 # 🔍 Your code goes here

composer.json and the magento directory are needed so that your app can function as a Magento theme
package.json specifies certain information about your app - such as its name and the packages it needs to work
yarn.lock keeps track of the exact dependency versions you have installed. The dependencies themselves live in node_modules
src and public are empty right now - but we will write some code in them!

🏃‍♀️ Running the App

We haven't even written any customization code yet, but the Scandi app can work out of the box!

cd my-first-app/
npm start

The start command will run your app at http://localhost:3000/ and open it in the browser.

Note: the app is only visible to you – nobody on the internet can see your Scandi app at the moment. The npm start command is for working on your app while testing it on your computer, not for production use.

If you browse around, you will see CMS content and products. But you probably don't have an instance of Magento running on your computer, so where is this data coming from?

By default, scandipwa-app is configured to forward all requests to a remote Magento instance. There are of course other configurations available, but we'll stick with the proxy for the purposes of this guide – its the fastest to set up.

Known issue: If you come across an iframe covering the entire screen when starting ScandiPWA app, please check here: https://stackoverflow.com/questions/69051008/react-injecting-iframe-with-max-z-index-on-reload-after-changes-development

🔍 Quick Tour

How come we got a beautiful working app without writing a single line of code? What you see is the "base" Scandi theme. Its code can be found in node_modules/@scandipwa/scandipwa/src/ – it is a dependency of your app. We can take a look inside to get an idea of how it works

node_modules/@scandipwa/scandipwa/src/
├── component/
├── index.js
├── query/
├── route/
├── service-worker.js
├── style/
├── store/
├── type/
└── util/

Here are the most important directories you need to know about:

🎨 Customizing Your App

The app works, but looks just like any other Scandi app. You probably want to customize some of its features. As a first step, let's customize the copyright footer.

Before we can modify its code, we need to know which component is responsible for rendering the Footer. We can use the browser's developer tools to find out. First, inspect the HTML element associated with the footer:

The developer tools should open, giving you information about the element. The element you selected will appear highlighted:

Note the class of the element you found. This might be slightly different depending on where you clicked – in our case, it is Footer-Copyright. What does this tell us about the component? Because Scandi follows strict Block-Element-Modifier (BEM) conventions, this gives us the name of the component – Footer (the first part of the class, called the Block, is always the same as the component name).

Now that we have found out the name of the component, there is only one place we need to look – the component directory in node_modules/@scandipwa/scandipwa/src/. Indeed, we can find a component named Footer there:

Original File in scandipwa/src/component/Footer/Footer.component.js

// [...]
export class Footer extends PureComponent {
    // [...]
    
    renderCopyrightContent() {
        const { copyright } = this.props;

        return (
            <ContentWrapper
              mix={ { block: 'Footer', elem: 'CopyrightContentWrapper' } }
              wrapperMix={ { block: 'Footer', elem: 'CopyrightContent' } }
              label=""
            >
                <span block="Footer" elem="Copyright">
                    { copyright }
                    { ' Powered by ' }
                    <a href="https://scandipwa.com">
                        ScandiPWA
                    </a>
                </span>
            </ContentWrapper>
        );
    }

    render() {
        return (
            <footer block="Footer" aria-label="Footer">
                { this.renderContent() }
                { this.renderCopyrightContent() }
            </footer>
        );
    }
}

export default Footer;

That funny HTML-in-JavaScript syntax is called JSX. Scandi uses the React library to render its user interface, and JSX is the easiest way to use React.

Now that we have found the component, we can update its code. But don't edit the file we found in node_modules – modifying dependency code is almost always a bad idea. (It would be hard to get updates, and difficult to track which of the many files you have edited). Instead, let's override it.

🎭 Override Mechanism

Scandi offers a great way to customize any component, and its called the Override Mechanism. With the override mechanism, you can override any file you want, while keeping the default implementations for the other files. This gives you great flexibility without having to duplicate any code.

To override a file, you need to create a new file with the same path in your src directory. For example...

To override:
    component/Footer/Footer.component.js
    (in node_modules/@scandipwa/scandipwa/src/)

...you need to create a new file:
    component/Footer/Footer.component.js
    (in src/)

Instead of manually creating a new file, you can save yourself a lot of time by using the Scandi CLI. With a single command, you can override the Footer component:

scandipwa override component Footer

When you run that command, the Scandi tool will ask you which components you want to override. Select the Footer class in Footer.component.js; leave the other fields blank:

Now we have created the file, which overrides the original Footer component file. Now, we want to import the original class, so that we can keep most of the Footer functionality, and extend it to customize its behavior:

File override in src/component/Footer/Footer.component.js

// We will need the ContentWrapper component later - let's import it
import ContentWrapper from 'Component/ContentWrapper';


// Import the original class (we want to keep most of the functionality)
// Note that we are using the "SourceComponent" alias in the import path –
// This tells Scandi that we want to get the original Footer component
import {
    Footer as SourceFooter
} from 'SourceComponent/Footer/Footer.component';


// Extend the original class (SourceFooter)
// By subclassing it, we can change some of its behavior
/** @namespace myFirstApp/Component/Footer/Component/FooterComponent */
export class FooterComponent extends SourceFooter {

    // This is the function responsible for rendering copyright
    // We want to change it, so we re-define in this subclass
    renderCopyrightContent() {
    
        // Changed:
        // Instead of the copyright text, let's write a friendly message
        return (
            <ContentWrapper
              mix={ { block: 'Footer', elem: 'CopyrightContentWrapper' } }
              wrapperMix={ { block: 'Footer', elem: 'CopyrightContent' } }
              label=""
            >
                <span block="Footer" elem="Copyright">
                    Thank you for visiting my website. You are amazing!
                </span>
            </ContentWrapper>
        );
    }
    
    // All the other functions will stay the same...
    // Because we didn't override any other default functionality
}

// All components, including the original Footer component, have a
// default export. Other files use this export when they want to use
// this component.
// Now, instead of providing the original component, we export our
// overridden component. Any file importing this will get the new behavior!
export default FooterComponent;

🔥 Hot Reload

Scandi implements hot reload – which means that you don't need to compile the app again. Just check your browser and the changes should have appeared.

Congratulations! Now you understand the basics of file overriding – and you can override any file in the app to change its behavior.

👋 Need Help?

If you get stuck or have any questions, we'd be happy to help! Feel free to drop us a message in Slack – all tech-related questions are welcome in the #pwa-tech channel.

Now you have your very own Scandi app. Let's deploy so you can brag about it 😂 – all it takes is one command:

scandipwa deploy

The Scandi CLI will do its magic, and give you the URL of your deployed app. You can check if your updated message is in the Footer – it should still be there, but this time, accessible to anyone on the internet!

📍 What Next?

Now that you know the basics of working with Scandi, you can explore the rest of the ecosystem. What you choose to do will depend on your needs and is entirely up to you:

Want some more hands-on experience? Stop by our tutorial section!
Learn about extensions – plugins you can easily install to get additional functionality
Want a working Magento backend to go with your app? Try create-magento-app!
Want to improve your workflow? Check out our recommended development environment.
Get a more in-depth understanding of Scandi's structure