CONTRIBUTING.md

Contributing

Thanks for being interested in contributing to this project!

Development

Setup

Clone this repo to your local machine and install dependencies.

pnpm install

We use VitePress for rapid development and documenting. You can start it locally by

pnpm build // vitepress depends on package generated css file
pnpm dev

Contributing

Existing Components

Feel free to enhance existing components, functions, and make new ones. Please try not to introduce breaking changes.

New components or functions

You only need to write code for Vue component, Svelte component will be automatically generated, there are some rules to follow though:

• v-bind variables needs to be last in order of attributes:

<button class="" :class=""></button>

• for watch expression in Vue, 2nd parameter arrow function's block needs to be Svelte compatible, 2nd parameter arrow function's parameter needs to be same name as watch expression first parameter:

watch(
	() => props.show,
	(show) => {
		showAlert.value = show ? true : false;
	},
	{ immediate: true }
);

• Write your functions in arrow function format:

const functionVariable = (...) => {...}

Adding new components or functions

• Before you start working, it's better to open an issue to discuss first.
• Component implementation should be placed under packages/vue/components as a folder and exposing in components/index.ts.
• Component types and theme configurations should be placed under packages/theme folder
• Component documentation should be placed under packages/core folder,
• Function implementation should be placed under packages/use/functions as a folder and exposing in functions/index.ts. Functions should be only components related. Function types and documentations should be placed in the same folder.
• In vue package, try not to introduce 3rd-party dependencies as these packages are aimed to be as lightweight as possible.
• If you'd like to introduce 3rd-party dependencies, please create a new add-on.

Project Structure

Monorepo

We use monorepo for multiple packages

packages
  vue/            - vue components package
  svelte/         - auto generated svelte components package
  use/            - shared functions (composables) across packages
  usevue/         - shared functions (composables) that are using vue as external dependency
  config/         - configuration
  theme/          - Interfaces and theme values for components properties and events
  metadata/       - AgufaUI metadata
  transform/      - transform vue components to svelte components
  locale/         - language files
  translate/      - translate en language file to other language files
  [...addons]/    - add-ons named

other folders under packages
  core/           - components documentation
  guide/          - guide documentation
  public/         - static assets for vitepress
  .vitepress/     - vitepress docs site

Documentation

for core/**/index.md the first sentence will be displayed as the short intro in the component list, so try to keep it brief and clear.

Function Folder

for use/functions/**/index.ts you should export the function with names.

folder name must be same as function name for auto metadata utils. /use/functions/index.ts will be auto generated by "nr udpate" command at root level.

pnpm run -w update

for index.md the first sentence will be displayed as the short intro in the function list, so try to keep it brief and clear.

Auto generate .svelte files

Files will be generated in packages/svelte/src/lib folder.

pnpm run post

This step is included in "pnpm run build" command.

Auto generate language files

You only need to modify packages/locale/lang/en.ts file for i18n, then run command and other language files will be generated in packages/locale/lang folder

pnpm run translate

This step is not included in "pnpm run build" command.

Code Style

Don't worry about the code style as long as you install the dev dependencies. Git hooks will format and fix them for you on committing.

Thanks

Thank you again for being interested in this project!