Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:

Node.js

Version 18.x or higher

npm

Comes bundled with Node.js

Git

For cloning the repository

Python Backend

Backend API server (optional for development)

​
Installation

1

Clone the repository

Clone the MkDowner repository from GitHub:
git clone https://github.com/UlisesGarcia20/app-markdown.git
cd app-markdown
2

Install dependencies

Install all required npm packages:
npm install
This will install the following key dependencies:
  • React 19.2.0
  • React Router DOM 7.9.6
  • SweetAlert2 11.26.3
  • TypeScript and Vite dev tools
3

Configure environment variables

Create a .env file in the project root and configure the backend API URL:
VITE_API_BASE_URL=http://localhost:5001
The VITE_ prefix is required for Vite to expose the variable to the client-side code.
Make sure your Python backend is running on the configured port before attempting file conversions.
4

Start the development server

Launch the Vite development server:
npm run dev
The application will start on http://localhost:5173 by default.
VITE v7.2.2  ready in 342 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help
5

Open and test the application

Open your browser and navigate to http://localhost:5173.You should see the MkDowner interface with:
  • Hero section with “Transform Documents into Markdown”
  • Drag-and-drop upload area
  • File format information
Try uploading a PDF or DOCX file to test the conversion!

​
Available Scripts

The project includes several npm scripts defined in package.json:
ScriptCommandDescription
devviteStart development server with hot reload
buildtsc -b && vite buildType-check and build for production
linteslint .Run ESLint to check code quality
previewvite previewPreview production build locally

​
Development Workflow

# Start dev server
npm run dev

# In another terminal, run linter
npm run lint

# Build for production
npm run build

# Preview production build
npm run preview

​
Troubleshooting

If you see “Cannot connect to server” errors:
  1. Verify the backend is running on the configured port
  2. Check the VITE_API_BASE_URL in your .env file
  3. Ensure no firewall is blocking the connection
The error handling code from api.ts:
catch (error) {
  if (error instanceof TypeError && error.message.includes('fetch')) {
    throw new Error('Cannot connect to server. Make sure backend is running on ' + API_BASE_URL);
  }
  throw error;
}
If port 5173 is already in use, Vite will automatically try the next available port. You can also specify a custom port:
npm run dev -- --port 3000
If you encounter TypeScript errors during build:
  1. Make sure all dependencies are installed: npm install
  2. Delete node_modules and reinstall: rm -rf node_modules && npm install
  3. Check TypeScript version: npx tsc --version (should be ~5.9.3)
The application supports files up to 24MB. If you need to increase this:
  1. Update the frontend validation in your upload component
  2. Configure the backend to accept larger files
  3. Consider adjusting nginx/reverse proxy limits if deployed

​
Development Tips

Hot Module Replacement (HMR) is enabled by default. Save any file and see changes instantly without losing application state.
The app uses React 19’s new features. Make sure to familiarize yourself with the latest React patterns if you plan to extend the codebase.

​
Project Structure

app-markdown/
├── src/
│   ├── components/        # React components
│   │   ├── Container/
│   │   ├── FileList/
│   │   ├── Header/
│   │   ├── SupportedFormats/
│   │   ├── Switch/
│   │   └── UploadArea/
│   ├── hooks/            # Custom hooks
│   │   ├── useConversionMode.ts
│   │   └── useFileUpload.ts
│   ├── services/         # API services
│   │   └── api.ts
│   ├── types/           # TypeScript types
│   │   └── index.ts
│   ├── App.tsx          # Main app component
│   ├── App.css          # Global styles
│   └── main.tsx         # Entry point
├── public/              # Static assets
├── .env                 # Environment variables (create this)
├── package.json         # Dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── vite.config.ts       # Vite configuration
└── eslint.config.js     # ESLint configuration

​
Building for Production

When you’re ready to deploy:
1

Build the application

npm run build
This creates an optimized production build in the dist/ directory.
2

Test the production build

npm run preview
Preview the production build locally before deploying.
3

Deploy

The dist/ folder contains all static assets. Deploy to:
  • Azure Static Web Apps (config included in staticwebapp.config.json)
  • Vercel, Netlify, or any static hosting service
  • Your own web server

​
Next Steps

Now that you have MkDowner running, explore these topics:

File Upload

Learn about the drag-and-drop functionality

Components

Explore the React component architecture

Custom Hooks

Understand the useFileUpload hook

API Integration

Connect to the backend conversion service

Build docs developers (and LLMs) love

Get started for freeTalk to us