Tracking is the step that converts a set of source files in a repository into a component that is semantically understood by Bit. The bit add command defines sets of files as components and start the component isolation process. The command analyzes the source files to build the component's dependencies. Tracking a component adds it to the components map in the workspace. The component is considered an "authored" component inside this workspace.
When tracking a component Bit does the follow:
- Calculate all the files to be included in the component.
- Exclude the following files:
.bitmapand files ignored in the
.gitignorefile, if available.
- Calculate the ID of the component.
- Calculate the entry point of the component and build the dependency graph for both external dependencies (npm packages) as described here and internal Bit components.
- Verify that all required files are tracked inside a component (this component or another one).
- Verify that each file is only tracked by a single component (a file cannot be tracked by multiple components).
Starting upcoming version, the rules bellow will also apply, so we suggest tracking components according to them to avoid future problems:
- All the files belong to the same component should reside under a single directory.
- Referencing files tracked by other components is with the component name only and not by relative paths or aliases.
bit status command also shows any errors during the tracking of a component.
Here are some recommendations on how to track components:
- Track each component as a single folder. Folder components lets bit track the whole folder, and you can make changes to the files in the component while Bit is still trackign them.
- Start tracking components bottom-up, so all components that are shared by other components are tracked first.
- Plan and arrange components in namespaces according to their functionality, similar to the way you would arrange them in folders in a project.
- Ensure all component files are located in a single folder.
- Review the package.json in your original projects to ensure proper definition of dependencies.
- If you are using path aliases in your
importstatements, make sure you define Bit's custom paths resolution configuration.
Each component has a unique identifier. The unique identifier is compound as follow:
<remote scope>/<namespace(s)>/<local name>.
Set namespaces with the
--namespace flag or by specifying the full path in the component name such as
Bit sets by default the component name to the folder name. To change it, specify a different name with the
--id name when adding the component.
To track a single component, use the
bit add command and specify the path to the folder or files of the component. (See comment above regarding tracking files in different folders).
bit add src/components/button
To track multiple components, use the
bit add command and specify the root folder and
/*. Bit adds each folder as a separate component.
bit add src/components/*
Component entry point
The entry point file is the file that is set as the main entry when compiling the file. You can specify the main file using the
--main flag on the bit add command. If the main file was not specified, Bit is trying to determine the main file as follow:
- If the component has only one file, it will be the main file
- If the component has a file named index with a valid extension like js, ts, tsx etc.
- If the component has a file named similarly to the component folder name with a valid extension as above.
You can specify the test files of the component, by preceding their name with the
--tests flag. Tests files are marked as such.
Manage component's files
When a folder is tracked by Bit, Bit detects any changes to the files such as adding or removing files and updates the component's tracked files accordingly.
To explicitly add files to the component, use the component's id:
bit add src/foo.js --id foo/bar
The exclude flag is going to be deprecated. Use the
--excludeflag to mark files located in the folder but are not part of the component.
# Move file to a new location bit move src/foo/bar/index.js src/components/new/location/index.js # Rename a file bit move src/foo/bar/index.js src/foo/bar/new-name.js # Move a folder that's part of a tracked component to a new location bit move src/foo src/components/new/location/foo
Adding component action can be reverted using the bit untrack command. You can only untrack new components. A component that is already tagged or exported, and imported components can be only removed.
To untrack a single component:
bit untrack hello/world
You can also untrack multiple components by specifying their ids:
bit untrack foo/bar foo/baz
To track all the newly added component use the
bit untrack --all
Common Isolation Errors
Here are some common errors and their resolution when trying to isolate a component. Run
bit status to check the status of components dependency resolution.
When a component is importing local files (i.e. files with relative paths), Bit is attempting to find the components where those files exist. If the file is not yet tracked by any other components, Bit notifies about an untracked dependency.
Handling these files can be in one of two manners:
- Add the file(s) as dependency to the same component.
- Add the file(s) as new components.
The decision between those two options is mostly contextual. Files that are shared between multiple components should reside as a separate component. Files that are local to the component, such as local styles, should be part of the same component.
To add a file to the component run:
bit add <filename> --id <component id>
To add files as new component, use the
bit add command. Bit automatically detects that the component was created and shows the updated status.
Missing package dependencies
This error may occur in the following cases:
- Some of the project's package dependencies are not installed
- The project is using a Custom Module Definition, or
NODE_PATHenvironment variable in your project and Bit is unaware of that.
As described above, Bit has different strategies to determine a package dependency version. If all of them fail, Bit prompts to install the missing package dependencies.
Use your package manager of choice to resolve the issue.
Alternatively, Bit issues a
missing package dependency error for tracked components, in a project, that have file dependencies to absolute paths, using Custom Module Definition feature. See here how to configure Bit with your project's custom paths resolution.
Components with Relative Import Statements
Bit expects the dependency tree of components to be defined using absolute
import statements. This is because Bit create and manage a set of link files (bindings) between imported components. So when you are using an imported component from another tracked component, or modifying an imported component, and adding an
import statement to another imported component, Bit will trigger this isolation issue.
In order to resolve this, you need to understand that Bit creates a link file for each of the project's imported component within the
node_modules directory. This allows you to require a component just as you would require a Bit package dependency with the same name, as shown here.
To resolve this issue you will need to refactor the
require statement in your code to the component dependencies, using Bit's package naming convention, and save the changes.
Non-existing Dependency Files
When Bit tracks files in your project, it evaluates their dependency tree. If one of the files in the component's dependency tree is not found within your project, Bit throws this isolation error. To resolve this issue, open the file, and ensure that the
require statement points to the correct file.
When Bit installs components, it creates a set of binding files to ensure that all imported component's dependency trees are working correctly. If any of these files is missing, Bit will prompt this isolation error. To fix this, you need to run the
bit link command. Bit will ensure all link files are in place.