Handleiding voor het uploaden van componenten

Componenten uploaden naar comp-hub kost maar drie stappen: map selecteren, preview configureren en op publiceren klikken.

Vereisten

Zorg er vóór het uploaden voor dat het component aan de volgende voorwaarden voldoet:

1. Mapstructuur: componenten moeten als mappen bestaan, waarbij de mapnaam de naam van het component is
2. Entry-bestand: er is een entry-bestand vereist — index.vue voor Vue-componenten, index.jsx / index.js / index.tsx voor React-componenten
3. Zelfstandig uitvoerbaar: componenten moeten op zichzelf staan, met dependencies die via relatieve paden worden geïmporteerd

Aanbevolen mappenstructuur:

MyComponent/           # Component name
├── index.vue         # Entry file (required)
├── README.md         # Component documentation (recommended)
├── comp.json         # Configuration file (auto-generated)
└── assets/           # Static resources (if any)
    └── logo.png

Uploadlimieten

De volgende limieten gelden bij het uploaden van componenten:

Limiet	Beschrijving
Bestandsgrootte per bestand	Elk bestand mag niet groter zijn dan 3MB. Comprimeer grote bestanden (audio, video, afbeeldingen met hoge resolutie) voordat je ze uploadt
Totale grootte	Alle bestanden van het component samen mogen niet groter zijn dan 10MB
Aantal bestanden	Het totale aantal bestanden (inclusief submappen) mag niet groter zijn dan 30

Als je bij het indienen een fout over de bestandsgrootte ziet, controleer dan op te grote statische bestanden en comprimeer of verwijder ze voordat je het opnieuw probeert.

Ondersteuning voor UI-frameworks

Component-previews kunnen draaien op Vue of React. Alle UI-frameworks uit beide ecosystemen kun je direct gebruiken.

Hoe het framework wordt herkend

Je geeft het framework nergens op. comp-hub leidt het af uit de dependencies in de broncode van het component:

• Het component importeert vue → het wordt behandeld als een Vue-component
• Het component importeert react → het wordt behandeld als een React-component
• Een component dat zowel vue als react importeert → het framework kan niet worden bepaald en de uploadpagina kan het niet controleren of renderen

Vue-componenten

Voeg voor Vue-componenten een main.js-bestand toe in de hoofdmap van het component en registreer het gewenste UI-framework:

Vue 2

import Vue from 'vue';
import Antd from 'ant-design-vue';
import 'ant-design-vue/dist/antd.css';
Vue.use(Antd);

Vue 3

Let op: Vue 3 exporteert standaard geen app-instantie. Hier wordt Vue.app intern door de tool aangemaakt en op Vue gemount. Dit wijkt af van de officiële aanpak waarbij je zelf createApp() aanroept — gebruik het gewoon direct.

import * as Vue from 'vue'
import ArcoVue from '@arco-design/web-vue';
import '@arco-design/web-vue/dist/arco.css';

Vue.app.use(ArcoVue);

React-componenten

React-componenten hebben geen main.js-bestand nodig en dependencies worden niet in comp.json aangegeven — import ze gewoon in je component zoals gebruikelijk:

import { Button, Card } from "antd";
import { LikeOutlined } from "@ant-design/icons";

export default function MyCard() {
  return <Card>Hello</Card>;
}

Wanneer je de map van het component op de uploadpagina selecteert, scant comp-hub de import-statements in je bronbestanden, lost elke dependency op vanuit de node_modules van je lokale project en prebuilt deze voor de preview. Dat betekent:

• Elke dependency die het component gebruikt, moet al lokaal in het project geïnstalleerd zijn (npm install <pkg>); anders meldt de preview een ontbrekende dependency
• De gevonden dependencies en hun versies staan op het tabblad Dependencies van het configuratiegebied, waar je ze vór publicatie kunt controleren
• Het entry-bestand moet een default export hebben; een component met alleen benoemde exports faalt met Component has no default export
• Zowel React 18 (react-dom/client) als React 17 (react-dom) wordt ondersteund — de juiste render-API wordt automatisch gekozen

Naamgevingsconventies

• Componentnamen zijn uniek binnen dezelfde ruimte (de openbare hub, of één team) en mogen niet samenvallen met bestaande namen
• Slechts twee formaten zijn toegestaan: PascalCase (UserGrowthChart) of kebab-case (alipay-data-table)
• Niet ondersteund: underscores _, camelCase (myComponent) en namen die met een cijfer beginnen
• Prefix-naamgeving wordt aanbevolen, bijvoorbeeld company-business-domain-component-name: alipay-data-table

Omgaan met dubbele componenten

Het platform voert een gelijkenisdetectie uit op geüploade componenten. Als het component als dubbel wordt beoordeeld:

• Komt het niet in openbare lijsten zoals "Aanbevolen", "Populair" en "Nieuwste"
• Kan het alleen worden bekeken en beheerd in "Mijn componenten"
• Verschijnt het in de aanbevolen lijst van vergelijkbare componenten
• Genieten updates ook niet van aanbevelingsgewicht

Het is aan te raden om vóór het uploaden te controleren of er functioneel vergelijkbare componenten zijn, zodat je het wiel niet opnieuw uitvindt.

Uploadstappen

1. Uploadpagina openen

Klik na het starten van comp-hub op "Component uploaden" in het linkermenu.

2. Component selecteren

• De bestandsboom links toont de map die is opgegeven met dir in .comphub.json of .comphub.js
• Navigeer naar de map van het component en selecteer deze
• Klik op "Selecteren" om te bevestigen

3. Preview configureren

De uploadpagina is verdeeld in een bovenste en een onderste gebied:

Bovenste previewgebied

• Realtime weergave van het renderresultaat van het component
• Ondersteunt verversen en wisselen van de achtergrondkleur

Onderste configuratiegebied

• Klein venster preview: kies het bestand dat op de lijstpagina wordt gerenderd — volgens afspraak demo/index.vue (of het component zelf)
• Volledig scherm preview: kies het bestand dat op de detailpagina wordt gerenderd — volgens afspraak demo/full.vue (aanbevolen)
• Dependencies: automatisch uit je broncode gedetecteerde dependencies met hun lokale versies; controleer ze hier
• Opmerkingen: korte beschrijving van de functie en de toepassingsscenario's van het component
• Extra informatie: uitgebreide beschrijving, ondersteunt zoekwoorden

Elk bestand in de componentmap dat eindigt op .vue, .jsx of .tsx kan als previewbestand worden gekozen — de map demo/ is een afspraak, geen vereiste. Gebruik voor React-componenten .jsx / .tsx-bestanden.

4. Configuratie genereren

Klik op de knop "Configuratie genereren" en het systeem maakt automatisch een comp.json-bestand aan met:

{
  "__id__": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "MyComponent",
  "version": "1.0.0"
}

comp.json bevat precies deze drie velden. __id__ wordt door de server ingevuld na de eerste succesvolle publicatie — pas het niet handmatig aan. Dependencies worden uit je broncode gehaald, niet uit dit bestand.

5. Component publiceren

Klik nadat je hebt gecontroleerd of de configuratie klopt op de knop "Publiceren" om de upload af te ronden.

Minimaal voorbeeld

Hier is een zo eenvoudig mogelijk component dat je kunt uploaden:

<!-- MyButton/index.vue -->
<template>
  <button class="my-button" @click="handleClick">
    {{ text }}
  </button>
</template>

<script>
export default {
  name: 'MyButton',
  props: {
    text: {
      type: String,
      default: 'Click Me'
    }
  },
  methods: {
    handleClick() {
      this.$emit('click')
    }
  }
}
</script>

<style scoped>
.my-button {
  padding: 8px 16px;
  background: #409eff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}
</style>

Minimaal React-voorbeeld

// MyCard/index.jsx
import { Card } from "antd";

export default function MyCard({ title = "Hello" }) {
  return <Card>{title}</Card>;
}

antd moet lokaal in het project geïnstalleerd zijn; de default export is verplicht.

Best practices

• Schrijf een README: gedetailleerde uitleg van het gebruik, de properties, events en voorbeelden van het component
• Lever een demo mee: maak een demo-map om het typische gebruik van het component te laten zien
• Semantische versionering: volg de specificatie major.minor.patch
• Ga goed om met dependencies: third-party dependencies hoef je alleen lokaal te installeren, je hoeft ze niet in het component te bundelen