Vue Leaflet Plugins

Appearance

Contribution Guide ​

A comprehensive guide on contributing to vue-leaflet-plugins, including project structure, development workflow, and best practices.

We welcome all contributions through bug reports, pull requests, and feedback to help make this library even better.

Before You Report

Before reporting a bug or requesting a feature, make sure that you have read through our documentation and existing issues.

Project Structure ​

Here's an overview of the key directories and files in the vue-leaflet project structure:

Documentation ​

The documentation lives in the docs folder as a Vitepress app to generate pages from Markdown files. See the Vitepress documentation for details on how it works.

Wrapper ​

The wrapper code resides in the src folder. Here's a breakdown of its structure:

DANGER

THIS NEEDS TO BE UPDATED

bash
├── leaflet.hotline/
│   ├── index.ts         # Make your components available here
│   └── ...              # Component files or folders    
├── ...                  # Other plugin folders
├── plugin-template
│   ├── index.ts         # Make your components available here
│   ├── LTemplate.vue
│   └── template.ts       
├── libs
│   ├── leaflet.hotline.ts
│   └── ...              # Place the plugin src here if not available via npm
└── plugins.ts

🛠️ Creating a New Plugin ​

Vue Leaflet Plugins provides a consistent way to wrap Leaflet plugins as Vue 3 components. Follow this guide to add your own plugin:

1. Copy the Template folder ​

  1. Go to src/template/.
  2. Copy the folder and rename it with the name of the Leaflet plugin.

2. Create the Component ​

Rename the files and replace all template and Template with appropriate names.
Follow the guide in vue-leaflet to create your component.

3. Register the Component ​

Place all your exports in your-plugin/index.ts.
In src/plugins.ts export your plugin so it’s available to users:

ts
export * from "./your-plugin";

4. Add a Playground Example ​

  • Add a usage example in playground/app/pages/your-plugin.
  • Showcase how to import and use your new plugin.
vue
<LMap>
  <LTileLayer url="..." />
  <LMyPlugin option1="test" :option2="5" />
</LMap>

You can create multiple examples here. Make sure that you have at least one example for every component:

  • LComponent.vue -> component.ts

5. Write Tests ​

  • Add tests in tests/components/.

  • Use Vitest to verify that:

    • The component mounts correctly.
    • Props are bound to the Leaflet instance.
    • Events are emitted if applicable.

Read the vue-leaflet-guide for more.

6. Update the Documentation ​

  • The documentation files for your components are autogenerated.
  • Check the documentation file to verify everything is working.

✅ Done! Now your plugin is ready to be shipped with vue-leaflet-plugins 🎉

Submit a Pull Request (PR) ​

Before you start, check if there's an existing issue describing the problem or feature request you're working on. If there is, please leave a comment on the issue to let us know you're working on it.

If there isn't, open a new issue to discuss the problem or feature.

Local Development ​

To begin local development, follow these steps:

Clone the vue-leaflet-plugins repository to your local machine ​

sh
git clone https://github.com/Maxel01/vue-leaflet-plugins.git

Install dependencies ​

sh
pnpm install

Start development ​

To make sure the development environments work correctly, build the wrapper first:

sh
pnpm build

You can select which build should be used for the dev environment. Open the nuxt.config.ts in the playground or vite.config.ts in the vue-playground and select local, dist or npm.

WARNING

Please make sure to revert your changes in the configuration to dist when pushing.

  • To work on the documentation located in the docs folder, run:
sh
pnpm docs:dev

To regenerate the files from the vue components, you need to restart the dev server.

TIP

The documentation always uses the dist folder. Build the wrapper first.

  • To test the vue-leaflet components using the playground, run:
sh
pnpm dev
  • To test the components using the Vue playground, run:
sh
pnpm dev:vue

Type Checking ​

We use TypeScript for type checking. You can use the type-check command to check for type errors:

sh
pnpm type-check

Testing ​

Before submitting a PR, ensure that you run the tests:

sh
pnpm test

Commit Conventions ​

We use Conventional Commits for commit messages, which allows a changelog to be auto-generated based on the commits. Please read the guide through if you aren't familiar with it already.

  • Use fix and feat for code changes that affect functionality or logic
  • Use docs for documentation changes and chore for maintenance tasks

Making a Pull Request ​

  • Ensure your PR's title adheres to the Conventional Commits since it will be used once the code is merged.
  • Multiple commits are fine; no need to rebase or force push. We'll use Squash and Merge when merging.
  • Ensure lint, typecheck and tests work before submitting the PR. Avoid making unrelated changes.
  • Use format before submitting the changes.

We'll review it promptly. If assigned to a maintainer, they'll review it carefully.

Thanks ​

Thank you again for being interested in this project! You are awesome! ❤️