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 = (...) => {...}

• always use shorthand, use : instead of v-bind:, use @ instead of v-on:, etc..

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 postpkdbuild

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.

Places to check when adding new components #

1. packages/vue/components folder to add new component
2. packages/vue/compnents/index.ts file to export new component
3. packages/theme/types folder to add interface for props and emits
4. packages/theme/default folder to add default theme configuration new component types
5. packages/theme/default.theme.ts file to add new component types to default theme
6. packages/theme/index.ts file to export default theme new component types and Interfaces, note that interfaces need to be named export for vue to pickup interface definition
7. packages/core folder to add docs for new Component
8. scripts/postpkgbuild.ts file updateSvelte(...) function to map folder name to file name if they are different (button folder and Abutton.vue are considered same name, superscript folder and Asup.vue are considered different name). And update noComputedProp and noImport variables if needed, noComputedProp means don't generate computed properties for these variable names, noImport means don't generate import statement for these library names.
9. packges/transform/src/vue/svelte folder genScript.ts file and genTemplate.ts file, if rules needs to be added or updated for generating svelte component.
10. packages/locale/lang/en.ts file if needs to add i18n for new component, then run pnpm run translate to generate other language files. New component name should be defined in packages/theme/default.theme.ts file.

Debugging external library #

eg. Debug Unocss #

1. create a new directory "test" somewhere else, in "test", clone project "git clone https://github.com/unocss/unocss"
2. suppose you debug in "theme" package, now under "theme" directory, add local dependency "pnpm add -D ../../../test/unocss/packages/unocss"
3. now you can add debug lines in unocss project files, eg. in "unocss/packages/vite" package, you add code "console.log('hi')" in src->modes->global->build.ts; under "unocss/packages/vite" directory, run "pnpm run stub"; under "theme" directory, run "pnpm run build" to see changes in console log.

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!