Skip to content

Latest commit

 

History

History
349 lines (252 loc) · 13 KB

ANGULAR.md

File metadata and controls

349 lines (252 loc) · 13 KB

Table of Contents

Getting started with Angular

This guide covers how to get started with Connected Components for Angular components.

👀 We simplified the Connected Components experience, you can now get it running within minutes. Check this document for details.

Zeplin provides an easier way to connect components using Storybook integration, if your Angular components already have corresponding stories in a Storybook environment. Check out this article to learn more.

1. Prepare configuration file

The first thing we'll do is to create a JSON configuration file in our repository that maps components in our codebase to the components in Zeplin.

You can either prepare the configuration file:

In this guide, we'll prepare the file manually, while also mentioning how you can use the extension to simplify all of the steps.

Create configuration file

Manual configuration

We recommend creating your Zeplin configuration file under the .zeplin folder in your repository, so let's create that folder first. Within the folder, also create a file called components.json and paste the JSON below:

{
    "projects": [],
    "styleguides": [],
    "components": []
}

Using VS Code Extension

If you use the Visual Studio Code extension, it should prompt you to create the configuration file. You can also use the “Create Zeplin Configuration File” command by pressing “Command/Ctrl + Shift + P”. After creating the configuration file, make sure to click the “Login” link on top of the file to authenticate with your Zeplin account.

In a bit, we'll start filling out the configuration file:

  • projects and styleguides keys are the identifiers of projects and styleguides we'll use components from.
  • components are the Angular component files in our codebase.

Add projects or styleguides

Manual configuration

Now, let's add Zeplin projects or styleguides to the configuration file. If you're using Global Styleguides, adding your styleguide(s) will be enough. If instead your components are under projects, you can add all your projects as well. In this example, we'll only add one styleguide.

To add projects or styleguides, we need their identifiers. If you're not using the Visual Studio Code extension, the easiest way to find the identifier of a Zeplin project or a styleguide is to open them in Zeplin's Web app. Look for the URL in the address bar, which should look like so: https://app.zeplin.io/styleguide/5cd486b18a64c1414be004fb. The identifier after styleguide/ (or project/) is the identifier we're looking for.

Using VS Code Extension

If you're using the Visual Studio Code extension, simply click “Add styleguide” or “Add project” and you'll be presented with a list.

After adding projects or styleguides to our configuration file, it should look like so:

{
    "projects": [],
    "styleguides": [
        "5cd486b18a64c1414be004fb"
    ],
    "components": []
}

☝️ If you have a styleguide tree and want to connect to all the components in the tree, adding a child styleguide to the configuration should be enough.

Add component from codebase

Manual configuration

Adding a component from your codebase to the configuration file is pretty straightforward—we'll add an object to the components list.

In this example, we'll go with a button.ts file under src/material/button. Pick a reusable Angular component file from your codebase and let's update our configuration file to look like so:

{
    "projects": [],
    "styleguides": [
        "5cd486b18a64c1414be004fb"
    ],
    "components": [
        {
            "path": "src/material/button/button.ts",
            "zeplinIds": []
        }
    ]
}

Using VS Code Extension

If you're using the Visual Studio Code extension, click the “Add component” link which will list all the files in your repository. Pick the one you want and your configuration file should look like the below example.

{
    "projects": [],
    "styleguides": [
        "5cd486b18a64c1414be004fb"
    ],
    "components": [
        {
            "path": "src/material/button/button.ts",
            "zeplinIds": []
        }
    ]
}

Next up, we'll populate the zeplinIds key.

Connect to component from Zeplin

It is recommended to use Zeplin CLI initialize flow or use VS Code Extension to add zeplinIds into the configuration file.

Manual configuration

Using zeplinNames is deprecated in favor of zeplinIds. If you are looking for the older guide check out here.

Now it's time to connect the Angular component we just added, to a component in Zeplin. We'll do that by adding component ids to the zeplinIds list.

Open Zeplin's Web app and navigate to the component you want to connect. Select the component and look for the URL in the address bar, which should look like: https://app.zeplin.io/styleguide/5dd4166f2387f13fc8b27ace/components?coid=5dd41717b4eaa04034df4c6f. The part after coid= is the identifier we're looking for, which is 5dd41717b4eaa04034df4c6f on the last example.

Let's add this identifier to the zeplinIds list:

{
    "projects": [],
    "styleguides": [
        "5cd486b18a64c1414be004fb"
    ],
    "components": [
        {
            "path": "src/material/button/button.ts",
            "zeplinIds": [
                "5dd41717b4eaa04034df4c6f"
            ]
        }
    ]
}

It's possible connect a component in our codebase to multiple components in Zeplin—let's do that:

{
    "projects": [],
    "styleguides": [
        "5cd486b18a64c1414be004fb"
    ],
    "components": [
        {
            "path": "src/material/button/button.ts",
            "zeplinIds": [
                "5dd4171a6825f144e068f1c6",
                "5dd41717b4eaa04034df4c6f",
                "602f60b5dd16708b272ace28"
            ]
        }
    ]
}

Using VS Code Extension

If you're using the Visual Studio Code extension, you can simply click “Connect to Zeplin component” and search for a component in Zeplin, directly within Visual Studio Code.

Next up, we'll install and use Zeplin's CLI tool so that these connected components are visible in Zeplin to our team.

2. Install Zeplin CLI

Zeplin CLI runs in your terminal and communicates the configuration file with Zeplin.

Let's start by installing it. Zeplin CLI runs on Node.js, if you don't have it installed already, see Node.js website.

To install Zeplin CLI from npm, run the following command on your Terminal/Command Prompt:

npm install -g @zeplin/cli

# Or install locally as devDependency

npm install -D @zeplin/cli

Alternatively, if you're using npm in your project, you can add @zeplin/cli as a devDependency.

3. Install CLI Angular plugin

Zeplin CLI uses plugins to generate documentation, snippets and links from components—check out our list of plugins.

Since we're using Angular, we'll install the official Angular plugin from npm, by running the following command:

npm install -g @zeplin/cli-connect-angular-plugin

# Or install locally as devDependency

npm install -D @zeplin/cli-connect-angular-plugin

Now, we'll update our configuration file to use the plugin. We can do that by adding it under the plugins list, like so:

{
    "plugins": [
        {
            "name": "@zeplin/cli-connect-angular-plugin"
        }
    ],
    "projects": [],
    "styleguides": [
        "5cd486b18a64c1414be004fb"
    ],
    "components": [
        {
            "path": "src/material/button/button.ts",
            "zeplinIds": [
                "5dd41717b4eaa04034df4c6f"
            ]
        }
    ]
}

Next up, we'll run the CLI command!

4. Run Zeplin CLI

It's time! Let's run the CLI command and see Connected Components in action within Zeplin. 🎉

Run the following command—if it's your first time, you'll need to login to Zeplin first:

zeplin connect

If @zeplin/cli and the plugin is locally installed, add a zeplin connect script on package.json:

{
    ...
    "scripts": {
        ...
        "zeplin-connect": "zeplin connect"
        ...
    }
    ...
}

Run the script:

npm run zeplin-connect

Now head back to Zeplin and click on one of the components you connected. You should see an output similar to this:

Connected component in Zeplin

Congratulations, we just connected our first component! 🎉

By default, Angular plugin only displays of the possible selectors of the component. In most cases this should be enough to get a glimpse of how the component can be used. If you want to see all the possible combinations, it's possible to configure the plugin like so:

{
    "plugins" : [
        {
            "name": "@zeplin/cli-connect-angular-plugin",
            "config": {
                "useFullSnippet": true,
                "useFullDescription": true
            }
        }
    ],
…
}

Once configured, you should see an output similar to this:

Connected component in Zeplin

For further information on how components are analyzed by the Angular plugin, check out the repository.

☝️ If you want to see the output locally in Zeplin before you publish it to your team, check out our guide on testing your changes locally.

5. Add links (Optional)

Connected Components also lets you add links to various sources like your Storybook, repository, wiki and so on. In the screenshot above, notice that we have links to GitHub and Storybook.

To add links to your components, check out these guides:

6. Connect more components

Now that we connected our very first component, you can go ahead and connect more! Check out the section Add component from codebase if you need any help.

Hope this getting started guide was helpful, reach out to us at [email protected] if you have any questions or feedback.

For further details on how to customize the configuration file, check out the Configuration file documentation.

Troubleshooting

If you run into any issues while running the zeplin connect command, make sure that you have the Angular plugin installed by running the following npm command:

npm list -g --depth 0 @zeplin/cli-connect-angular-plugin

If you can't see documentation or code snippets in Zeplin after you successfully run the command, please create an issue under the Angular repository.

Check out Troubleshooting for other common issues.

Related resources